Category Archives: org

Transpose a table in org-mode

I recently needed to transpose a table in org-mode and spent a few minutes trying to come up with a keyboard macro to do it before it occurred to me that there might be a command to do this already. And of course there was: M-x org-table-transpose-table-at-point. Here it is in action:

transpose-table.gif

It’s great when there’s a command that does exactly what you want!

Reschedule multiple items in org agenda

I (all too) often find myself failing to complete all the tasks I schedule for a particular day and so need to reschedule them in my org agenda. To do this (and other operations) on multiple items, mark the items in your agenda view using m then hit B to bring up the bulk action list and then s to reschedule. This will set the new scheduled date to all marked items.

Org-mode: Start a numbered list from any number

This trick is in the org-mode manual but it’s worth a quick mention in its own right. If you want to start a numbered list in org-mode from a number other than 1, then put [@N] at the start of the first item, where N is the number you want to start with. So for example,

 1) item 1
 2) item 2

This text would interrupt the list and the next item would be 1) on a
new list

 3) [@3] This will be item 3 thanks to [@3]
 4) and this will be item 4

Speed up pdf export from org-mode with latexmk

These days I write almost everything (e.g. research papers, lecture notes and slides) in org-mode, and then export to pdf (see my posts on org-mode here). This is a really pleasant and efficient way to create documents, but when working on a long document, it can take several seconds for emacs to compile the exported latex to pdf. During that time, emacs is hung up waiting for the compilation to finish, which is annoying.

I thought I’d share my workflow for streamlining this process. The key ingredient is not part of emacs. I use latexmk which is a perl script that watches a latex file and compiles it if it changes (or any file that it depends on changes). It will repeat the compilation (including calling bibtex) as many times as needed to resolve all references.

So, if I am working on a file, say document.org, I will run latexmk on the corresponding tex file using

latexmk -pvc -pdf -view=none document.tex

Here, the -pcv option means to keep watching the file for changes and recompile as needed; the -pdf option means build a pdf from the latex using pdflatex, and -view=none tells latexmk not to open a pdf viewer to show the resulting pdf.

I then open the resulting document.pdf in skim, an excellent pdf viewer for the Mac (unfortunately hosted on sourceforge). The killer feature of skim compared to the built-in OS X preview app, is that it will automatically redisplay a pdf if the file changes (I believe evince or okular on linux do the same).

Putting the pieces together, I have latexmk running in a terminal, and an emacs window and skim window side by side. I then export my org file to latex with e.g. C-c C-e l l which happens almost instantly and gives me control back of emacs. The latex is compiled in the background by latexmk and then a few seconds later the pdf updates in skim and I can see my changes.

Org-mode basics VII: A TODO list with schedules and deadlines

In this post we’ll build on the simple todo list that we put together previously and add schedules and deadlines to our tasks to build a powerful agenda.

When adding a task (with C-c c t) you can add a scheduled date to it with C-c C-s or a deadline date with C-c C-d, or both. These will pop up a calendar which you can navigate using shift and the arrow keys.

I prefer to schedule all new tasks to today’s date as a default, so I update the org-capture-templates variable to

(setq org-capture-templates
      '(("t" "todo" entry (file+headline "~/todo.org" "Tasks")
         "* TODO [#A] %?\nSCHEDULED: %(org-insert-time-stamp (org-read-date nil t \"+0d\"))\n")))

Now when you add a task, you will see a scheduled field like this

** TODO [#A]
SCHEDULED: <2015-12-08 Tue>

You can edit the date by putting the cursor in it and using shift + arrow keys.

Now instead of using C-c a t to view your list of tasks, we will use C-c a n to display a list of your scheduled tasks and then any unscheduled tasks below it.

I have several configuration options that I recommend. Add the following to your emacs config file if you like the look of them:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; org-mode agenda options                                                ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;open agenda in current window
(setq org-agenda-window-setup (quote current-window))
;;warn me of any deadlines in next 7 days
(setq org-deadline-warning-days 7)
;;show me tasks scheduled or due in next fortnight
(setq org-agenda-span (quote fortnight))
;;don't show tasks as scheduled if they are already shown as a deadline
(setq org-agenda-skip-scheduled-if-deadline-is-shown t)
;;don't give awarning colour to tasks with impending deadlines
;;if they are scheduled to be done
(setq org-agenda-skip-deadline-prewarning-if-scheduled (quote pre-scheduled))
;;don't show tasks that are scheduled or have deadlines in the
;;normal todo list
(setq org-agenda-todo-ignore-deadlines (quote all))
(setq org-agenda-todo-ignore-scheduled (quote all))
;;sort tasks in order of when they are due and then by priority
(setq org-agenda-sorting-strategy
  (quote
   ((agenda deadline-up priority-down)
    (todo priority-down category-keep)
    (tags priority-down category-keep)
    (search category-keep))))

With these options we get a really useful view of our tasks when using C-c a n. For example, here is a todo.org file with a mixture of tasks with and without schedules and deadlines

* Tasks
** TODO [#A] do this today
SCHEDULED: <2015-12-08 Tue>
** TODO [#A] do this tomorrow
SCHEDULED: <2015-12-09 Wed>
** TODO [#A] this task is not scheduled
** TODO [#B] scheduled for today, priority B
SCHEDULED: <2015-12-08 Tue>
** TODO [#A] scheduled today and deadline in 2 days
DEADLINE: <2015-12-10 Thu> SCHEDULED: <2015-12-08 Tue>
** TODO [#A] deadline in 2 days and not scheduled
DEADLINE: <2015-12-10 Thu>
** TODO [#A] scheduled for monday
SCHEDULED: <2015-12-14 Mon>
** TODO [#C] do this today if I get time
SCHEDULED: <2015-12-08 Tue>
** TODO [#B] neither is this one
** TODO [#C] or this one
** TODO [#A] deadline in 10 days and not scheduled
DEADLINE: <2015-12-18 Fri>

When I view the agenda associated with this file I see this

example-agenda.png

Org-mode basics VI: A simple TODO list

In the first part of my series on org-mode, I described how to create a rich structured notebook that can be exported to various useful formats. In the next few posts in this series I’m going to talk about another essential way I use org-mode, which is to organise myself! I use org-mode to manage my (depressingly long) task list including scheduled tasks and deadlines, to export a calendar feed for events, and to quickly capture useful information including emails and scanned documents. If you want to see a very advanced use case, look at Bernt Hansen’s Org Mode – Organize Your Life In Plain Text.

In this post, we’ll start by looking at setting up a simple todo list, and we’ll cover some of the more advanced topics later.

To start with, add the following code to your emacs config file:

;; set key for agenda
(global-set-key (kbd "C-c a") 'org-agenda)

;;file to save todo items
(setq org-agenda-files (quote ("/Users/bjm/todo.org")))

;;set priority range from A to C with default A
(setq org-highest-priority ?A)
(setq org-lowest-priority ?C)
(setq org-default-priority ?A)

;;set colours for priorities
(setq org-priority-faces '((?A . (:foreground "#F0DFAF" :weight bold))
                           (?B . (:foreground "LightSteelBlue"))
                           (?C . (:foreground "OliveDrab"))))

;;open agenda in current window
(setq org-agenda-window-setup (quote current-window))

;;capture todo items using C-c c t
(define-key global-map (kbd "C-c c") 'org-capture)
(setq org-capture-templates
      '(("t" "todo" entry (file+headline "/Users/bjm/todo.org" "Tasks")
         "* TODO [#A] %?")))

This sets up the file in which we will save our todo items (put your own choice of file here), configures a few other options, and sets up a capture template to quickly add todo items to the list (put the same file name for your todo file here too). Now you can highlight the code in your config file and use M-x eval-region or restart emacs to pick up the changes.

Once you have done this you can add your first todo item using C-c c t, which will pop up a small window with a prompt like this

** TODO [#A]

You can see this looks like an org-mode headline, and you should add your todo item and any notes to go with is to this like so:

** TODO [#A] make a todo list
Some notes here about how to do it

Then hit C-c C-c to save this item. The nice thing about this method of adding items (called org-capture) is that you can add an item from anywhere in emacs and get right back to what you were doing afterwards.

By default our item was given priority A, but you can change this easily by hitting shift and up or down arrow to cycle through the priority levels (I find that three levels, A-C is enough for me).

Let’s add a priority B item:

** TODO [#B] add another item to my list

Now we can have a look at our todo list using C-c a to launch the “agenda dispatcher”, a powerful interface for selecting different ways to view your tasks. For now we’ll just hit t in the dispatcher to view the todo items (i.e. use C-c a t). This switches to a buffer with our todo list – in this list view, you might want to:

  • Cross an item off your list (the best bit!). To do this put the cursor on the corresponding line and hit $ which marks it as done and archives the item in a file called todo.org_archive getting rid of it from your todo list.
  • Change the priority of an item using shift up/down.
  • View the notes to go with items by hitting E.
  • Edit or view an item in more detail by hitting RET with the cursor on the item that you want. This takes you to the item in your todo.org file where you can edit it or look at the notes you added to it in more detail.
  • Quit back to where you were before with q

That is all there is to it, and you now have a simple but powerful todo list in emacs. Just remember C-c c t to create a todo item and C-c a t to view the todo list.

That’s all for now. In the next part we’ll look at scheduling and deadlines.

Org-mode basics V: Exporting your notes

In this final post of my short series on using org-mode to write rich, structured notes, we will look at exporting the notes as a web page or pdf document. The previous posts covered structuring your notes and adding tables and links and images, and formatting text and source code.

If you have been following along, you should have an org file containing all of the notes on org-mode from the previous posts. We’ll now look at exporting that file.

One strength of org-mode is the ability to export to multiple formats. Probably the most useful to begin with are web pages and pdf (via latex) but more are available; to quote the org manual

ASCII export produces a readable and simple version of an Org file for printing and sharing notes. HTML export allows you to easily publish notes on the web, or to build full-fledged websites. LaTeX export lets you use Org mode and its structured editing functions to create arbitrarily complex LaTeX files for any kind of document. OpenDocument Text (ODT) export allows seamless collaboration across organizational boundaries. Markdown export lets you seamlessly collaborate with other developers. Finally, iCal export can extract entries with deadlines or appointments to produce a file in the iCalendar format.

To export your org file to a web page, type C-c C-e to start the exporter and then press h to select html and o to select open. A new web page should now open in your browser.

Similarly, typing l and o in the exporter will convert the org file to latex and then compile it to produce a pdf and display that. Try both of these.

It is possible to add many customisations to the export process. For example, go to the top of the buffer (using M-<) and use C-c C-e and then # to insert an export template. You can then choose to add html or latex (or other) templates (press TAB to see the list).

As an example, add the following to the top of your org file to tweak the appearance of the exported documents.

#+LaTeX_CLASS: bjmarticle
#+TITLE:     Org-mode Basics
#+AUTHOR: Ben Maughan
#+OPTIONS: html-link-use-abs-url:nil html-postamble:auto
#+OPTIONS: html-preamble:t html-scripts:t html-style:t
#+OPTIONS: html5-fancy:nil tex:t
#+HTML_DOCTYPE: xhtml-strict
#+HTML_CONTAINER: div
#+DESCRIPTION:
#+KEYWORDS:
#+HTML_LINK_HOME:
#+HTML_LINK_UP:
#+HTML_MATHJAX:
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.star.bris.ac.uk/bjm/css/bjm.css" />
#+HTML_HEAD_EXTRA:
#+SUBTITLE:
#+INFOJS_OPT:
#+CREATOR: <a href="http://www.gnu.org/software/emacs/">Emacs</a> 24.4.1 (<a href="http://orgmode.org">Org</a> mode 8.3.2)
#+LATEX_HEADER:

This is the default html export template with a couple of tweaks.

  • I have added a link to a style sheet to style the html
  • I have added a latex class bjmarticle to control the appearance of the generated pdf

The latex class is defined in my emacs config file with the following

(add-to-list 'org-latex-classes
             '("bjmarticle"
               "\\documentclass{article}
\\usepackage[utf8]{inputenc}
\\usepackage[T1]{fontenc}
\\usepackage{graphicx}
\\usepackage{longtable}
\\usepackage{hyperref}
\\usepackage{natbib}
\\usepackage{amssymb}
\\usepackage{amsmath}
\\usepackage{geometry}
\\geometry{a4paper,left=2.5cm,top=2cm,right=2.5cm,bottom=2cm,marginparsep=7pt, marginparwidth=.6in}"
               ("\\section{%s}" . "\\section*{%s}")
               ("\\subsection{%s}" . "\\subsection*{%s}")
               ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
               ("\\paragraph{%s}" . "\\paragraph*{%s}")
               ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

You’ll need some experience of LaTeX to make significant changes here, but the sky is the limit.

I have compiled the series of posts on org-mode basics into a single org file, and exported it with this set of export options.

  • The org file is here
  • The exported web page is here
  • The exported pdf is here

The wrapping of the example and code blocks in the pdf needs to be fixed, but overall we get some pretty nice looking documents with minimal effort.

Wrap text in an org-mode block

In my most recent post on org-mode, I talked about using blocks to mark text as being latex, or source code and so on. I mentioned using the shortcuts like <e then TAB on a new line to create an empty block. Sometimes it is handy to wrap existing text in a block, and the following function does that for the text you have selected.

This has been in my config file for ages and I can’t remember where it came from – I know I didn’t write it! A bit of googleing suggests this could be the origin, but if anyone knows different, let me know.

I bind the function to C-< because it reminds me of the < shortcuts to create the blocks, and I don’t use the org-cycle-agenda-files that is usually bound to that key combo.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; function to wrap blocks of text in org templates                       ;;
;; e.g. latex or src etc                                                  ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun org-begin-template ()
  "Make a template at point."
  (interactive)
  (if (org-at-table-p)
      (call-interactively 'org-table-rotate-recalc-marks)
    (let* ((choices '(("s" . "SRC")
                      ("e" . "EXAMPLE")
                      ("q" . "QUOTE")
                      ("v" . "VERSE")
                      ("c" . "CENTER")
                      ("l" . "LaTeX")
                      ("h" . "HTML")
                      ("a" . "ASCII")))
           (key
            (key-description
             (vector
              (read-key
               (concat (propertize "Template type: " 'face 'minibuffer-prompt)
                       (mapconcat (lambda (choice)
                                    (concat (propertize (car choice) 'face 'font-lock-type-face)
                                            ": "
                                            (cdr choice)))
                                  choices
                                  ", ")))))))
      (let ((result (assoc key choices)))
        (when result
          (let ((choice (cdr result)))
            (cond
             ((region-active-p)
              (let ((start (region-beginning))
                    (end (region-end)))
                (goto-char end)
                (insert "#+END_" choice "\n")
                (goto-char start)
                (insert "#+BEGIN_" choice "\n")))
             (t
              (insert "#+BEGIN_" choice "\n")
              (save-excursion (insert "#+END_" choice))))))))))

;;bind to key
(define-key org-mode-map (kbd "C-<") 'org-begin-template)

Org-mode basics IV: formatting text and source code

This is a continuation of my series of introductory posts on org-mode that are focussed on simple text-based notes. We looked already at structuring your notes and adding tables and links and images to your notes. In this post we will look at formatting the text in your notes.

For today we will look at the effect of formatting on the plain text view of your notes, but very soon we will come to exporting your notes to html and pdf and we’ll see that the formatting is applied to the exported documents very nicely.

We will also look at including executable code in your notes. Hopefully you can see that by putting all these pieces together you can build a very powerful document of your research containing your data, notes, relevant links, source code and results.

As before I suggest adding the notes below to your growing org file. For technical reasons I have to display the notes as plain text below but if you paste them into your org file you’ll see them nicely formatted and coloured like this:

* Formatting text
** Simple formatting
You can apply simple formatting to your text by enclosing words in
special characters. These include
 - /italicised text/
 - *bold text*
 - _underlines_
 - =literal text=
 - ~code~ (generally appears the same as literal text)

Here are the full notes:

* Formatting text
** Simple formatting
You can apply simple formatting to your text by enclosing words in
special characters. These include
 - /italicised text/
 - *bold text*
 - _underlines_
 - =literal text=
 - ~code~ (generally appears the same as literal text)

** Formatted blocks of text
For longer pieces of text you can enclose the text in blocks marking
it as a specific sort of text. I commonly use these ones

#+BEGIN_EXAMPLE
This is an example block into which you can type text that you don't want org to mess with like a [[link]]. This will typically be rendered in a monospace font when exported.
#+END_EXAMPLE

#+BEGIN_QUOTE
This block encloses text that you want to appear as a quotation.
#+END_QUOTE

#+BEGIN_CENTER
This text will be centred when it is exported.
#+END_CENTER

You can save time typing out the block wrapper by using shortcuts. Go
to the start of a new line and type <e and press TAB and it will
expand to an example block. The same works for <q for quote and <c for
centre.

** LaTeX
Org-mode does a good job of understanding snippets of LaTeX (a
[[https://www.latex-project.org/][powerful typesetting language]] used in scientific and other technical
documents). For example, it will correctly export simple superscripts
x^2 or subscripts x_0 or symbols like \alpha, \beta, \gamma.

Org also understands more complex LaTeX like this

\begin{eqnarray}
x^2 + \left(\frac{y}{z}\right)^4 = 0
\end{eqnarray}

but for longer bits of LaTeX it is better to use a LaTeX block. You
start one with <l and TAB

#+BEGIN_LaTeX
LaTeX code goes here
#+END_LaTeX

** Source code blocks
It is also handy to include source code in your notes - on a new line
type <s and TAB to create a source block. You can tell org what type
of code is contained - in this case we'll put in some simple shell
code, so well put "sh" at the top of the block.

#+BEGIN_SRC sh
  echo "Hello $USER! Today is `date`"
  exit
#+END_SRC

You can get org to syntax highlight the text in the block by adding
the following to your [[http://pragmaticemacs.com/emacs/editing-your-emacs-config-file/][emacs config file]] (without the source block
wrapper of course).

#+BEGIN_SRC elisp
;;syntax highlight code blocks
(setq org-src-fontify-natively t)
#+END_SRC

What is more, when the cursor is inside a SRC block, you can use C-c '
to create a new temporary buffer in the major mode of the programming
language you have specified. Type some code in, and then type C-c '
again to come back to this buffer.

** Executing source code blocks
Org-mode can execute your source code blocks and add the output to
your file. This part of org-mode is called babel. I'll write more
about this later, but it is too cool not to mention here.

For example, take the simple code block we had above:

#+BEGIN_SRC sh
  echo "Hello $USER! Today is `date`"
  exit
#+END_SRC

Put the cursor inside the block and hit C-c C-c to execute it. You
will be asked to confirm and then you should see the output appear
like this:

#+RESULTS:
#+begin_example
Hello bjm! Today is Fri 25 Sep 2015 15:03:12 BST
#+end_example

You can do much more with this, like reading input data from a table
in the same file, creating images that appear in the file, extracting
(tangling) all the code snippets into one or more files to be executed
separately, and much more. [[http://orgmode.org/worg/org-contrib/babel/intro.html][Here are some nice examples]].

You can tell org-mode which programming languages to support by adding
something like the following to your [[http://pragmaticemacs.com/emacs/editing-your-emacs-config-file/][emacs config file]]:

#+BEGIN_SRC elisp
;; Some initial languages we want org-babel to support
(org-babel-do-load-languages
 'org-babel-load-languages
 '(
   (sh . t)
   (python . t)
   (R . t)
   (ditaa . t)
   (perl . t)
   (gnuplot t)
   ))
#+END_SRC

Org-mode basics III: add links and images to your notes

In this series of introductory posts on org-mode we have been focussing on simple text-based notes. We looked at structuring your notes and adding tables to your notes. Next we will look at adding links and images. Links can be to files, URLs or locations in the current org document. If the link is to an image then emacs can display it inline in the org document. This is handy for enhancing your notes and will also be useful when we come to look at exporting to different formats.

As before I suggest adding the notes below to your growing org file. Note that below I have formatted the notes as plain text because org-mode changes the appearance of links, such as hiding the [] around links, which is nice in your org-mode document but makes it harder for me to show you what is going on!

* Links and images
Org mode supports links to files, URLs, and to other points in the org
file. In this example let's use an image from my website. First copy
it to the current directory. You can do this within emacs but for now
just run this command in your terminal.

curl http://www.star.bris.ac.uk/bjm/superman_cluster.gif -o superman_cluster.gif

To add a link to a file use C-u C-c C-l and type the name of a file.
Use tab-completion to select the image we just copied and you will
then be asked for a description - you can press enter to leave this
blank. This will create a link that looks like this

[[file:superman_cluster.gif]]

If you do this in your org file, you wont see the [[ ]] above, instead
you'll see the text as a clickable link.

Since the file we have linked to is an image, we can tell emacs to the
image in the document using C-c C-x C-v and use the same command to
turn the image off again.

You can also click the link with the mouse, or use C-c C-o to follow
it, which might open your web browser, an image viewer or open a file
in emacs depending on the target of the link.

The structure of a link in org mode looks like this

#+BEGIN_EXAMPLE
[[link address][description]]
#+END_EXAMPLE

(I've enclosed the link in an example block which prevents org-mode
from trying to interpret as a real link, for the purpose of showing
its structure - we'll come back to blocks like this later.)

The link address is the URL or file name, and the description is the
text that is displayed, so we can replace our superman link with
something tidier like [[file:superman_cluster.gif][this]].

Links to web pages are easy - just put the http address in as the link
address. Use C-c C-l as a quick way to add such a link (remember we
used C-u C-c C-l is for adding a link to a file).

Links to other parts of the org file are added easily like [[Links and
images][this link]]. Because the address part of the link matches a
headline in this document, then org-mode points the link to that part
of the file. Clicking it will move the cursor there.

Finally, we can add a caption and a name to our image like this

#+CAPTION: Superman and a galaxy cluster
#+NAME: fig.super
[[file:superman_cluster.gif]]

which means we can refer to our image later with a link like this one
[[fig.super]]

That’s all for now. Next time I think we’ll look at some simple text formatting.