Org-mode

1. Org-Mode
2. Org-mode Elisp Snippets and Org-mode API

1 Org-Mode

1.1 Overview

Org-Mode is a mode built-in to Emacs that allows to store structured data, information in text format - org-mode markdown that can be exported to html, pdf, latex, markdown, github flavoured markdown and more file formats.

Features:

Everything stored in text format: The most portable format.
Todo List.
It can be used as a personal Wiki.
Table editing, formating, built-in spreadsheet.
Tags, Headlines
Literate programming, Run code blocks, Create Interactive and reproducible software documentation.
Display and export Latex Formulas
Display Pictures
Many link formats
- Link to files, web, IRC, Usenet News groups
- Link to shell commands
- Links to trigger Emacs Functions
Usefulness
- Authoring
- Write Software documentation with embedded snippets
- Literate Programming
- Reproducible Research
- Wiki
- Markdown

Example: this document is now written in org-mode and the exported to html and github flavoured markdown.

It also supports inline code blocks that can be evaluated and the result printed in the document or displayed in the minibuffer.

1.2 Key bindings and commands for org-mode mode org key binding

1.2.1 Useful Commands

Command	Description

Display
M-x org-toggle-inline-images	Toggle images display
M-x org-toggle-latex-fragment	Toggle latex formulas display
M-x org-toggle-link-display	Toggle hyperlink display

Export
M-x org-html-export-to-html	Export buffer to html file.
M-x org-latex-export-to-pdf	Export buffer to pdf file.

Search
heml-occur	Useful quick search and navigation.
helm-org-in-buffer-headings	Filter org-mode files by headlines.

1.2.2 Hyperlink

Key binding	Description
C-c C-l	Insert hyperlink at point
C-c C-o	Open hyperlink at point

1.2.3 Move within headlines

Key Binding	Description
M - <return>	Insert headline at same level as the previous one.
C-c C-p	Move to previous headline
C-c C-n	Move to next headline
C-c C-u	Move to higher headline
M-[up]	Move headline, list row or table row up
M-[down]	Move headline, list item or table row down
M-[left]	Demote list item or headline
M-[right]	Promote list item or headline

1.2.4 Buffer Subtree

Key Binding	Description
shift-tab	Fold / Unfold headlines
C-x n s	Narrow the buffer subtree to current headline
C-c n w	Widen the view back

1.2.5 Table

Key Binding	Description
C-c-!	Convert region into a table

1.2.6 Hyperlinks

Key Binding	Description
C-c-C-o	Open a link
C-c-C-l	Insert/ Edit a link

1.3 Markdown Summary

1.3.1 Text Formatting

Example	Code
bold	`bold`
italics	`/italics/`
*very strong*	`/very strong/`
underline	`_underline_`
`verbatim`	`~verbatim~`
~~strike through~~	`+strike through+`
`inline code`	`=inline code=`

1.3.2 Hyperlinks

Description	Formatting	Output
Link to a file	`file:/etc/fstab`	file:///etc/fstab
Link to a web page	`http://www.httpbing.org/get`	http://www.httpbing.org/get
Email	`mailto:dummy@gmail.com`	mailto:dummy@gmail.com
Usenet Link	`news:comp.emacs`	comp.emacs
Info - Documentation	`info:gcc`	gcc
Shell Command	`shell:uname%20-a`	uname%20-a
Elisp code	`elisp:(info%20"gcc")`	(info%20"gcc")
Doi - Digital object identifier	`doi:10.1000/182`	10.1000/182

Hyperlinks from org-contrib:

Description	Example
Link to manpage	`man:sed`	(require 'org-man)

1.3.3 Code Blocks

Summary

Description	Shortcut	Code
Soource code block	<s	`#+BEGIN_SRC ... #+END_SRC`
Example	<e	`#+BEGIN_EXAMPLE ... #+END_EXAMPLE`
Quote	<q	`#+BEGIN_QUOTE ... #+END_QUOTE`
Verse	<v	`#+BEGIN_VERSE ... #+END_VERSE`
Center	<c	`#+BEGIN_CENTER ... #+END_CENTER`
Latex	<l	`#+BEGIN_LaTeX ... #+END_LaTeX`
Html	<h	`#+BEGIN_HTML ... #+END_HTML`
Ascii	<a	`#+BEGIN_ASCII ... #+END_ASCII`

Quote Block

Literal:

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

Output:

This block encloses text that you want to appear as a quotation.

Text Position

Center

Output:

This text is centered!

Literal:

#+begin_center
This text is  
centered!
#+end_center

Left

Output:

This text is
aligned to the left!

Literal:

#+begin_left
This text is \\
aligned to the left!
#+end_left

Right

Output:

This text is aligned to the right!

Literal:

#+begin_right
This text is 
aligned to the right!
#+end_right

Latex Code Block
Example1
```
\begin{equation}
\begin{align}
\mbox{Union: }  A\cup B = \{x\mid x\in A \mbox{ or } x\in B\} \newline
\mbox{Concatenation: } A\circ B  = \{xy\mid x\in A \mbox{ and } y\in B\} \\
\mbox{Star: } A^\star  = \{x_1x_2\ldots x_k \mid  k\geq 0 \mbox{ and each } x_i\in A\} \\
\end{align}
\end{equation}
```
Output:
\begin{equation} \begin{align} \mbox{Union: } A\cup B = \{x\mid x\in A \mbox{ or } x\in B\} \newline \mbox{Concatenation: } A\circ B = \{xy\mid x\in A \mbox{ and } y\in B\} \\ \mbox{Star: } A^\star = \{x_1x_2\ldots x_k \mid k\geq 0 \mbox{ and each } x_i\in A\} \\ \end{align} \end{equation}
Example2

1.4 Literate Programming Recipes

See: Org-mode-recipes.html

1.5 Resources

1.5.1 References

Manual:

Examples:

Emacs org-mode examples and cookbook

Many examples about literate programming in Org-mode with Python, R, java and C. Shows integration of org-mode tables and Python, R … and code blocks.

Reference Cards and Cheat Sheets:

Books:

Org Mode - Organize Your Life In Plain Text!

Hacking and Tweaking:

Cases:

Literate Programming:

Non Categorized:

Gareth's Org-Mode Config

1.5.2 Videos

Tutorials
Org Mode in Depth - by Rick Dillon
- Hack Emacs - Org Mode In Depth: Managing Structure - YouTube
Description: "Part of the Org Mode In Depth series. In this episode, we examine methods for exploiting the structure of an Org Mode file to focus on specific subtrees, control visibility by folding and unfolding headlines, navigate among headlines efficiently and reorganize headlines my moving and/or promoting and demoting them."
- Org Mode In Depth: Tables - YouTube
Description: "Actually recorded a few months back, I never got around to uploading this. I give a brief demo of some of the functionality Org Mode tables offer, and an explanation of some of the commands that enable it."
- Hack Emacs - Org Mode in Depth: Markup and Links - YouTube
Description: "Part of the Org Mode in Depth series. In this episode, I examine ways of marking up text in Org Mode, as well as various link types that connect Org headlines and files, as well as links that can execute code."

NOn-Programmer's Emacs: Studying in Emacs pt 3: Annotation with Orgmode by Tory S. Anderson
Presentations

2 Org-mode Elisp Snippets and Org-mode API

2.1 Org-mode API documentation

To access org-mode API documentation inside Emacs, copy the code below to the scratch buffer, then place the cursor at the end of any of those s-expressions and type C-x C-e or type M-x eval-last-sexp.

(info "(org)Library of Babel") 

(info "(org)Previewing LaTeX fragments")

(info "(org)Exporting code blocks") 

(info "(org)The export dispatcher") 

(info "(org)noweb")

2.2 Code Block Templates

When the user writes '<p'in org-mode and hits tab key it expands to a python source code block like this:

#+BEGIN_SRC python :results value

#+END_SRC

Elisp code:

(add-to-list 'org-structure-template-alist
             '("p" "#+BEGIN_SRC python :results ?value\n\n#+END_SRC"))

2.3 Code Blocks API

2.3.1 Overview

To test this the code block API divide the window in two parts, one cointaining a org buffer with some org-mode file and other one the emacs shell, IELM, that can be invoked with M-x ielm.
At the org-mode buffer position the cursor at the code block.
Go to the IELM buffer and run C-c C-b or type M-x ielm-change-working-buffer and change the working buffer to the org-mode buffer by typing its name and hitting tab to complete it.
Run the commands at the IELM shell. If it was done the command
- (buffer-name) will return the name of the org-mode buffer instead of *ielm*.

In this section, it is supposed that the org-buffer has this code block:

#+BEGIN_SRC scala :tangle /tmp/scalatest.scala
  import java.awt.BorderLayout
  import javax.swing.{JFrame, JPanel, JButton, JTextArea}

  val frame = new JFrame("Border Layout")
  val btn1  = new JButton("North")
  val btn2  = new JButton("South")
  val btn3  = new JButton("Center")
  val btn4  = new JButton("West")
  val btn5  = new JButton("East")

  frame.setLayout(new BorderLayout())
  frame.add(btn1, BorderLayout.NORTH)
  frame.add(btn2, BorderLayout.SOUTH)
  frame.add(btn3, BorderLayout.CENTER)
  frame.add(btn4, BorderLayout.WEST)
  frame.add(btn5, BorderLayout.EAST)

  frame.setSize(300, 400)
  frame.setVisible(true)
#+END_SRC

It would be rendered as:

import java.awt.BorderLayout
import javax.swing.{JFrame, JPanel, JButton, JTextArea}

val frame = new JFrame("Border Layout")
val btn1  = new JButton("North")
val btn2  = new JButton("South")
val btn3  = new JButton("Center")
val btn4  = new JButton("West")
val btn5  = new JButton("East")

frame.setLayout(new BorderLayout())
frame.add(btn1, BorderLayout.NORTH)
frame.add(btn2, BorderLayout.SOUTH)
frame.add(btn3, BorderLayout.CENTER)
frame.add(btn4, BorderLayout.WEST)
frame.add(btn5, BorderLayout.EAST)

frame.setSize(300, 400)
frame.setVisible(true)

2.3.2 Get information about code block

ELISP> (org-babel-get-src-block-info)
("scala" "import java.awt.BorderLayout\nimport javax.swing.{JFrame, JPanel, JButton, JTextArea}\n\nval frame = new JFrame(\"Border Layout\")\nval btn1  = new JButton(\"North\")\nval btn2  = new JButton(\"South\")\nval btn3  = new JButton(\"Center\")\nval btn4  = new JButton(\"West\")\nval btn5  = new JButton(\"East\")\n\nframe.setLayout(new BorderLayout())\nframe.add(btn1, BorderLayout.NORTH)\nframe.add(btn2, BorderLayout.SOUTH)\nframe.add(btn3, BorderLayout.CENTER)\nframe.add(btn4, BorderLayout.WEST)\nframe.add(btn5, BorderLayout.EAST)\n\nframe.setSize(300, 400)\nframe.setVisible(true)"
 ((:colname-names)
  (:rowname-names)
  (:result-params "replace")
  (:result-type . value)
  (:comments . "")
  (:shebang . "")
  (:cache . "no")
  (:padline . "")
  (:noweb . "no")
  (:tangle . "/tmp/scalatest.scala")
  (:exports . "code")
  (:results . "replace")
  (:hlines . "no")
  (:session . "none"))
 "" nil 0 2257)

ELISP>

2.3.3 Getting the programming language of the code block

ELISP> (car (org-babel-get-src-block-info))
"scala"
ELISP>

2.3.4 Getting the source code of the code block

ELISP> (cadr (org-babel-get-src-block-info))
"import java.awt.BorderLayout\nimport javax.swing.{JFrame, JPanel, JButton, JTextArea}\n\nval frame = ..."
ELISP>

ELISP> (print (cadr (org-babel-get-src-block-info)))

"import java.awt.BorderLayout
import javax.swing.{JFrame, JPanel, JButton, JTextArea}

val frame = new JFrame(\"Border Layout\")
val btn1  = new JButton(\"North\")
val btn2  = new JButton(\"South\")
val btn3  = new JButton(\"Center\")
val btn4  = new JButton(\"West\")
val btn5  = new JButton(\"East\")

frame.setLayout(new BorderLayout())
frame.add(btn1, BorderLayout.NORTH)
frame.add(btn2, BorderLayout.SOUTH)
frame.add(btn3, BorderLayout.CENTER)
frame.add(btn4, BorderLayout.WEST)
frame.add(btn5, BorderLayout.EAST)

frame.setSize(300, 400)
frame.setVisible(true)"

2.3.5 Getting code block attributes

ELISP> (caddr (org-babel-get-src-block-info))
((:colname-names)
 (:rowname-names)
 (:result-params "replace")
 (:result-type . value)
 (:comments . "")
 (:shebang . "")
 (:cache . "no")
 (:padline . "")
 (:noweb . "no")
 (:tangle . "/tmp/scalatest.scala")
 (:exports . "code")
 (:results . "replace")
 (:hlines . "no")
 (:session . "none"))

ELISP> (assoc :exports (caddr (org-babel-get-src-block-info)))
(:exports . "code")

ELISP> (cdr (assoc :exports (caddr (org-babel-get-src-block-info))))
"code"
ELISP>

ELISP> (assoc :tangle (caddr (org-babel-get-src-block-info)))
(:tangle . "/tmp/scalatest.scala")

ELISP> (cdr (assoc :tangle (caddr (org-babel-get-src-block-info))))
"/tmp/scalatest.scala"
ELISP>

2.3.6 Run a Scala code block

This example is specific for the Scala language, but can be easily adapated to other languages.

Usage:

Place the cursos at the some scala code block
run M-x org/run-scala-block

It will run save the code block content to the file /tmp/scala-snippet.scala and run the command $ scala /tmp/scala-snippet.scala in the compiling mode.

(defun org/run-scala-block ()
  (interactive)
         ;; Org-mode block contents 
  (let* ((content (cadr (org-babel-get-src-block-info)))
         ;; File in that the contents will be saved.
         (file    "/tmp/scala-snippet.scala"))
    ;; Execute the commands inside this special form
    ;; in a temporary buffer 
    (with-temp-buffer
      ;; Delete file if it exists
      (if (file-exists-p file) (delete-file file))
      ;; Insert the code block contents in the temporary buffer 
      (insert content)
      ;; Write the buffer contents to fil.
      (append-to-file (point-min) (point-max) file))    
    ;; Run the compilation command 
    (compile (format "scala %s" file))))

2.4 Custom Protocols

2.4.1 Open directory with dired mode

Org-mode already provides the protocol file:<filename> to open a directory or file. The motivation to implement this protocol is that it is unambiguous like file protocol and easy to search.

Hyperlink syntax: dir:<file-path>

(add-hook 'org-mode-hook
          (lambda ()
              (org-add-link-type "dir" #'dired nil)))

Org-mode file example:

Log directory      -  dir:/var/log  -  [[dir:/var/log][Log directory]]

System cofiguration - dir:/etc

2.4.2 Open directory with system file manager

Hyperlink format: dire:<directory-path>

(defvar default-file-manager-app "pcmanfm-qt")

(defun org/protocol-dire (input)
  (start-process  "proc" ;; Process name
                  nil    ;; Buffer name

                  default-file-manager
                  input
                  ))

(add-hook 'org-mode-hook
          (lambda ()
              (org-add-link-type "dire" #'org/protocol-dire nil)))

Example:

To open the directory file:/var/log in the system file
manager click on the hyperlink bellow.


 - Hyperlink1:   dire:/var/log

 - Hyperlink2:   [[dire:/var/log][System Log directory]]

2.4.3 Man page

Provides a hyperlink that displays a man page when clicked.

(add-hook 'org-mode-hook
          (lambda ()
                 (org-add-link-type  "man" #'woman nil)))

Example:

file test.org

Click on the hyperlinks bellow to open the man pages:

Gcc Man Page:

 - man:gcc

C-function cbrt Man Page

 - man:cbrt

 - [[man:cbrt][C-function cbrt Man Page]]

2.4.4 Elisp Documentation

Provides clickable link that shows the the Elisp documentation.

A link of format elisp-doc:add-hook will show the add-hook documentation when clicked.

Hyperlink format: elisp-doc:<function-name> or [elisp-doc:<function-name>]

(defun org/protocol-elisp-doc (function-symbol)
  (princ function-symbol)
  (describe-function (intern-soft function-symbol)))


(defun org/protocol-elisp-doc-html (path desc backend)
   (cl-case backend
     (html (format
            "<a href='' title='%s'>%s</a>"
            (documentation (intern-soft path))
            (or desc path)))))

(add-hook 'org-mode-hook
      (lambda ()
        (org-add-link-type "elisp-doc"
                           #'org/protocol-elisp-doc
                           #'org/protocol-elisp-doc-html)))

Example:

file: /tmp/test.org

Elisp documentation protocol:

[[elisp-doc:add-hook][Function Add hook]]

The function elisp-doc:start-process is used to start an asynchronous process.

This screenshot show what happens when the user clicks in the hyperlink.

Exported to html with: M-x org-html-export-to-html

2.5 Settings

2.5.1 General Settings

Syntax highlight for code blocks #+BEGIN_SRC .. #+END_SRC

;; Syntax highlight for code blocks  #+BEGIN_SRC .. #+END_SRC
;;
(setq org-src-fontify-natively t)

Syntax highlight for latex fragments

(setq org-highlight-latex-and-related '(latex script entities))

2.5.2 Code Block - Org-babel

Enable source code block in org files

(org-babel-do-load-languages
 'org-babel-load-languages
 '((emacs-lisp . t)
   (sh . t)
   (python . t)
   (scheme . t)
   (lisp . t)
   (clojure . t)
   (R . t)
   (latex . t)
   (ruby . t)
   (C . t)
   ;;; (C++ . t)
   (ditaa . t)
   (haskell . t)
 ;;  (fsharp . t)
 ;;  (java . t)
 ;;  (scala . t)
;;   (javascript . t)
   (maxima . t)
  ))

Disable Security confirmation:

;; Disable security confirmations
;;

(setq   ;; Confirmation for running coide blocks
        org-confirm-babel-evaluate      nil
        ;; Confirmation for elisp links
        org-confirm-elisp-link-function nil
        ;; Confirmation for shell links
        org-confirm-shell-link-function nil

        org-export-babel-evaluate       nil
        )

Org-mode

Table of Contents

1 Org-Mode

1.1 Overview

1.2 Key bindings and commands for org-mode mode org key binding

1.2.1 Useful Commands

1.2.2 Hyperlink

1.2.3 Move within headlines

1.2.4 Buffer Subtree

1.2.5 Table

1.2.6 Hyperlinks

1.3 Markdown Summary

1.3.1 Text Formatting

1.3.2 Hyperlinks

1.3.3 Code Blocks

1.4 Literate Programming Recipes

1.5 Resources

1.5.1 References

1.5.2 Videos

2 Org-mode Elisp Snippets and Org-mode API

2.1 Org-mode API documentation

2.2 Code Block Templates

2.3 Code Blocks API

2.3.1 Overview

2.3.2 Get information about code block

2.3.3 Getting the programming language of the code block

2.3.4 Getting the source code of the code block

2.3.5 Getting code block attributes

2.3.6 Run a Scala code block

2.4 Custom Protocols

2.4.1 Open directory with dired mode

2.4.2 Open directory with system file manager

2.4.3 Man page

2.4.4 Elisp Documentation

2.5 Settings

2.5.1 General Settings

2.5.2 Code Block - Org-babel