Intro to org-mode
Table of Contents
Installation
You need emacs (see my previous workshop for installation).
Org-mode comes with emacs so you don't need to install anything else.
What is org mode?
Org is an emacs major mode created by Carsten Dominik in 2003 and currently maintained by Bastien Guerry. It enjoys a huge popularity and hordes of developers keep growing it into a more and more powerful tool.
Here is a great description from the org mode manual:
"Org is a mode for keeping notes, maintaining TODO lists, and project planning with a fast and effective plain-text system. It also is an authoring system with unique support for literate programming and reproducible research.Org is implemented on top of Outline mode, which makes it possible to keep the content of large files well structured. Visibility cycling and structure editing help to work with the tree. Tables are easily created with a built-in table editor. Plain text URL-like links connect to websites, emails, Usenet messages, BBDB entries, and any files related to the projects.
Org develops organizational tasks around notes files that contain lists or information about projects as plain text. Project planning and task management makes use of metadata which is part of an outline node. Based on this data, specific entries can be extracted in queries and create dynamic agenda views that also integrate the Emacs calendar and diary. Org can be used to implement many different project planning schemes, such as David Allen's GTD system.
Org files can serve as a single source authoring system with export to many different formats such as HTML, LaTeX, Open Document, and Markdown. New export backends can be derived from existing ones, or defined from scratch.
Org files can include source code blocks, which makes Org uniquely suited for authoring technical documents with code examples. Org source code blocks are fully functional; they can be evaluated in place and their results can be captured in the file. This makes it possible to create a single file reproducible research compendium.
Org keeps simple things simple. When first fired up, it should feel like a straightforward, easy to use outliner. Complexity is not imposed, but a large amount of functionality is available when needed. Org is a toolbox. Many users actually run only a (very personal) fraction of Org's capabilities, and know that there is more whenever they need it.
All of this is achieved with strictly plain text files, the most portable and future-proof file format. Org runs in Emacs. Emacs is one of the most widely ported programs, so that Org mode is available on every major platform."
In one hour, I will barely scratch the surface of org-mode's capabilities. For more information, check its manual. The good thing is that you can start taking advantage of its simple features right from the beginning.
Demo of some of org mode's uses
I will very quickly show you a few of the things that I do in org mode.
And now…
Let's play with org mode!!!
Basics of org mode
Reminders from the workshop "intro to emacs"
Modifier keys:
C = control
M = meta (alt)
S = shift
A hyphen means that you have to press 2 keys simultaneously
e.g. "C-c" means "press control and the letter c at the same time"
A space means that you have to press 2 keys successively
e.g. "C-c C-x" means "press control-c then control-x"
Emacs has a lot of commands starting with C-x C- (e.g. C-x C-f to "find" a file, C-x C-s to "save" a file, C-x C-c to "close" a session).
Similarly, org mode has a lot of commands starting with C-c C-
Header structure
*_Header 1 **_Header 2 ***_Header 3
These various headers can easily be promoted, demoted (alone or with their entire subtree), moved up or down and their content can be shown or collapsed… amongst many other things.
M-<RET> create new heading just below C-<RET> create new heading at the end of the section TAB right after this will move this new heading at levels above and below its current level TAB otherwise cycles through the various states of visibility M-<left> promote one header M-<right> demote one header M-S-<left> promote header and its tree M-S-<right> demote header and its subtree M-S-<up> move header up M-S-<down> move header down
Challenge 1
You are creating a draft for a project and playing with ideas... First, you will find (create) an org file anywhere on your computer (I will help people who were not here for the intro to emacs workshop). And you name it "my-draft.org" and write (save) it. ------------------------------------------------------------ Reminder from the intro to emacs workshop: C-x C-f to find a file C-x C-s to write a file ------------------------------------------------------------ Then you create 3 main points called: "Idea 1", "Idea 2" and "Idea 3" and you type a few words in each section. You change your mind and decide that "Idea 3" should in fact come before "Idea 2". You add 2 sublevels for "Idea 1" called "Thought a" and "Thought b" and you type a few words in those as well. In "Thought a", you create 4 sublevels that you call "Argument 1", "Argument 2", "Argument 3" and "Argument 4". You change your mind again and decide that "Thought a" should become an additional main point (so you will promote it to a first header), while "Argument 3" and "Argument 4" should now become sublevels of "Argument 1" (do not use kill and yank for this. Think how you can very easily do this using org mode headings' functionalities). You change your mind one last time (drafting and playing with ideas is made of a lot of that!) and decide that "Thought a" and its sublevels should become a subtree of "Idea 3" Finally, cycle through the various visibility (only the overview, the whole tree structure or everything).
There are also commands to kill, copy, yank, duplicate, etc. sections or headers with their entire subtrees. Others to jump around from one header to another. And so many more.
You can have a look at the org manual for more information:
Lists
Starting a line with "-", "+" or a number/letter followed by "." or ")" will start a list. New items can be added with M-<RET> and all items can also be easily moved up/down, promoted/demoted, renumbered, have their list type changed (from "-" to numbers or letters) and so much more.
Here again, the org manual has a lot of additional information.
Challenge 2
Using the link above for a list of keybindings, add a few list items in one section of my-draft.org and play with various commands (move your list items around, make subitems, etc.).
Tables
Playing with org tables could be a whole workshop in itself. For now, just know that they are beautiful, easy, powerful and can even be used as spreadsheets for basic operations.
To give you a mini taste of what they look like, just type:
| header1 | header2 | header3
and then
C-c Ret
Et voilà!
Now start filling in your table. TAB will move you horizontally and reformat the table while RET will move you vertically.
Exporting
Documents created in org mode can be exported in all sorts of formats (latex and then pdf, html, etc).
To open the exporter, type: C-c C-e (The usual C-c org mode command and C-e as in "export")
Code blocks
Code blocks of many languages can be inserted in org mode for literate programming.
This is what an R code block looks like for instance:
#+BEGIN_SRC R
adult_dotplot <-
ggplot(adult, aes(mass)) +
geom_dotplot() +
ggtitle("Mass of adult Tuamotu Sandpipers") +
xlab("Mass (g)") +
theme_classic()
adult_dotplot
#+END_SRC
(Of course there are snippets that make it as easy as 2 keystrokes to create the codeblock start and end lines).
Codeblocks can be executed and you have a lot of control about what is exported when you covert your code to pdf, html, etc. (the code alone or the code and its output or just the output or nothing at all, etc.).
This is very similar to RMarkdown. Except that you can also embed latex codes, python codes, html codes, etc. And you can enjoy the endless functionalities of org mode...