On org mode

> index / blog : org mode

Introduction

org mode is a markup language, initially designed for task management within emacs. Since then, it has evolved into a markdown alternative for general note taking purposes. It has also export functionalities.

org mode is great for writing short and simple texts. For example, these blog pages are written in org mode and exported to html. For scientific writing, native LaTeX has more advantages, because things like author's affiliations, reference management, and layout customisation work better. In my experience, advanced options become increasingly more difficult to achieve and you get diminishing returns. Your document won't be true plain text anymore and the main argument for using org mode, that is its simplicity, is gone. At this point, you should use LaTeX.

When writing an org document, it is good practice to declare the document type with:

#+mode: -*- mode: org

The general syntax of modifying an org documents default behaviour is using #+<keyword>, followed by values.

Task management

Simple tasks require only two states, TODO and DONE. We can also define our own states, although I currently don't use this functionality:

#+todo: TODO WAIT IN-PROGRESS | DONE CANCELLED

The following creates a time stamp whenever a task is closed:

(setq org-log-done t)

The org-agenda view summarises tasks and can be used to scan across different files. In order to declare which files to scan, we use:

(setq org-agenda-files (list "~/org/scratch.org"
                             "~/org/misc.org"))

The list of tasks can then be displayed via M-x org-agenda.

A good workflow is to couple this with orgzly, to get the tasks synced between your mobile phone and your personal computer.

In addition, I currently have in my init.el, which opens the org-agenda view at start up:

(setq inhibit-splash-screen t)
(org-agenda-list)
(delete-other-windows)

Export

In general, org documents can contain metadata that will be used during export:

#+title: org mode
#+author: ilhan özgen xian

Other possible metadata is #+date. If it's not defined, org mode will use the system's clock.

html documents

By default, org mode creates html documents with javascript, whether it's needed or not. This behaviour can be modified as:

#+options: toc:nil html-scripts:nil num:nil

Here, toc:nil disables the table of contents, html-scripts:nil disables javascript, and num:nil disables numbered headings.

LaTeX documents

My LaTeX preamble looks like this:

#+latex_class: article
#+latex_class_options: [a4paper, draft]

Change draft to final once you are done. In general, I advise against using org mode to generate complex manuscripts.

Interactive notebooks

An interesting application of org mode is literate programming, or the ability to create notebooks that have executable code mixed with exposition. This is done through Babel, which ships with org mode. One advantage of using org mode is that it allows mixing different programming languages in the same session. The syntax for defining an active code block is:

#+begin_src python :session jupyter

The :session pde option specifies that the state of the workspace is saved and can be used further if it is referenced. This is useful for loading environment variables via bash. The list of languages that are allowed to be executed within org are defined in init.el as:

(org-babel-do-load-languages
'org-babel-load-languages
'((shell . t)
(python . t)
(R . t)))

We can also control what gets exported:

#+begin_src python :session jupyter :exports both

The :exports option takes keywords both, none, and code.

org mode's default behaviour is to ask for permission before evaluating a code block. This is for security reasons, but it gets tedious if there are a lot of blocks to be evaluated. In these cases, use:

(setq org-html-validation-link nil)

org-tree-slide

org-tree-slide presents different sections of an org-file as individual slides. Open an org-file and execute M-x org-tree-slide-mode. Then, navigate through the slides using C-> (forward) and C-< (backward).


Impressum

Author: ilhan özgen xian

Created: 2022-12-15 Thu 10:21