# Emacs and Org-Mode Tutorial

Ben Maughan, Room 4.19, Physics. Full contact information.

## 1 Introduction

This tutorial is intended to introduce the text editor Emacs and demonstrate some of the advanced techniques that are useful for researchers. In particular I will highlight the use of Emacs as a research notebook.

Note that to call Emacs a text editor is a bit of an understatement. It is also a web browser, news reader, email client, file manager, development environment, and the list goes on.

The structure of this tutorial is a general introduction to Emacs, with some preparatory work, and then an interactive session where I will demonstrate some techniques that you should work along with. To begin with you need to work through to the end of the Emacs basics section.

These tutorial notes were written as an org mode text document which you can download here (right click and save).

## 2 Initial setup

Here we will set up Emacs with spell checking. To get the most out of Emacs for scientific work, you'll find it useful to have a working LaTeX installation too.

### 2.1 Mac

The best way to install Emacs on the Mac is to use the homebrew package manager. Install homebrew from a terminal using the command

/usr/bin/ruby -e "(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"  Then install emacs and hunspell using brew install emacs --with-cocoa --with-gnutls --with-rsvg --with-imagemagick brew linkapps emacs brew install hunspell brew linkapps hunspell  Finally, download the hunspell dictionaries from here http://www.star.bris.ac.uk/bjm/hunspell-en_GB.zip and unzip the files into ~/Library/Spelling Alternatively, if you just want to install Emacs as a normal app, you can download Emacs for OSX which will work out of the box, except maybe for spell checking, which you can talk to me about. ### 2.2 Linux Linux machines come with emacs installed, ideally you should be using the most recent version of emacs (25.3.1), but I think everything below will also work in Emacs 24 onwards. You can check your emacs version with emacs --version  On the astronomy group's linux machines you can access the latest Emacs with alias emacs /usr/local/bin/emacs  and then run Emacs as usual Otherwise, contact your system admin to intall the latest version, or install it yourself with a package manager, or from source. You can install the latest bleeding edge version from source following these instructions: https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html You will also need a spell-checking program, and my Emacs configuration assumes you use hunspell. This can be installed by your package manager and you should just need to make sure it is in your PATH. ### 2.3 Windows Download this zip file which contains Emacs and the hunspell spell checker and extract it somewhere sensible - I used my home directory. Now run addpm.exe in the newly created emacs/bin directory to add emacs to your start menu. ### 2.4 All versions Now we will install a customised configuration file to add extra features to Emacs. The configuration file is where you can customise almost any aspect of Emacs to make it work just the way you want but for beginners I would suggest using my configuration file to start with and then making changes to it as you get more experienced. The configuration file for Emacs is ~/.emacs.d/init.el (or ~/.emacs for older Emacs versions). If you have previously changed your configuration then rename the file so that it won't get overwritten and won't confuse Emacs. To install my configuration file, do the following: • Start emacs and go to the buffers menu and choose scratch • Paste this line into emacs and then put the cursor at the end of the line and press control and j together (url-copy-file "http://www.star.bris.ac.uk/bjm/bjm-starter-init.el" (expand-file-name "~/.emacs.d/init.el") 1)  • Close and restart emacs and wait for it to finish installing packages • Close and restart emacs again You can check if you have the latest version by running the command C-h v bjm-init-version, and you should see version 1.7. For Windows you will need to edit the section of your init file that specifies where hunspell is. To do this, use M-x bjm/open-my-init-file and look for the section headed "CUSTOMISE - hunspell" (use C-s to search for this). ## 3 Emacs basics ### 3.1 Emacs tutorial Before we can get into some of the most useful areas of emacs and org-mode, you will need to learn the basics of how to operate emacs. The best way to do this is to work though the emacs tutorial. This is available under the help menu of emacs, and I will assume that you have worked through the tutorial, or already know the basics of emacs in the following. Note that our configuration changes some of the default emacs behaviour, but basic functions covered in the tutorial should work as described. ### 3.2 Key concepts Before we continue, make sure you are happy with the following basic concepts: • What the notation C- and M- means. e.g. C-x means hold down control and press x at the same time; C-x C-f means hold down control and press x then f; C-x f means hold down control and press x, then release control and press f. M- means the same for the meta key. This means the alt key on most keyboards, but this might be the command, option, or even escape key on a Mac. • How to open and save files (C-x C-f and C-x C-s) • How to move around a file (arrows, C-v, M-v, C-a, C-e, searching) • How to copy (M-w) kill/cut (C-w) and paste (C-y) • Deleting letters and words with C-d, M-d and BACKSPACE and M-BACKSPACE. Note also that undo and redo are set to C-z and C-Z in our configuration. • What is meant by buffers, windows, and frames, and how to switch between buffers (C-x C-b and C-x b) • How to quit out of a command (C-g) and quit emacs (C-x C-c) • How to run extended commands with M-x ## 4 Org-mode Emacs uses the concepts of modes to provide additional functionality. These are either major modes which relate to the type of file being edited (e.g. text-mode for text files, cperl-mode for perl files, nxml-mode for html, auctex-mode for latex etc), or minor modes that provide additional functionality. Major modes usually activate automatically when a file of a given type is opened, and only one major mode is active in a given buffer at a time. Minor modes also provide additional functionality, but can work across different major modes, and you can have as many active as you like. For example, flyspell-mode provides spell checking in many major modes. Additional major and minor modes can be installed using the emacs package manager (a bit like browser extensions). Org-mode is a very powerful major mode that provides the ability to create structured text documents, along with lots of other useful things. We will be using it here as a way to make a detailed notebook that includes code snippets, tables and images. Now, copy the tutorial org file your home directory by pasting the following line into your *scratch* buffer and putting the cursor at the end and hitting C-j. (url-copy-file "http://www.star.bris.ac.uk/bjm/emacs_tutorial.org" (expand-file-name "~/emacs_tutorial.org") 1)  Open the file with C-x C-f and Emacs will automatically start that buffer in org-mode. Now let's start work through the tutorial adding our own notes as we go First we can check we have a recent version of org mode using M-x org-version and check it is newer than 8.0. I have marked points in bold where you need to add text. ### 4.1 org-mode structure Text in org is structured by headings, denoted by lines starting with one or more * so we are currently in a subsection! add a sub-subheading #### 4.1.1 navigation Headings can be expanded or collapsed by moving to the (sub)heading and pressing TAB. S-TAB cycles all headings. You can jump to next and previous headings with C-c C-n and C-c C-p respectively. Alternatively if the cursor is at the start of a heading, you can use n p f and b to move between headings. expand and collapse headings and move between them You can move headings up and down with M-up and M-down. Try this now. #### 4.1.2 lists 1. bullet lists • bullet lists can be created like this (start a line with one or more space and a - • pressing M-RET gives you a new bullet • we might also like nested bullets • like this one (I pressed M-RET then M-right to indent it) • and another (M-RET now indents to the new level) • the nice thing is that for long lines of text, emacs wraps them so that they line up with the bullet • you can also reorder list items and change indentation using M-up or M-down just like with section headings • you can change bullet style using S-left and S-right Add an item to the list above and then move the items around and change the bullet style 2. numbered lists 1. numbered lists are also possible 2. M-RET gives me a new number 3. moving the items changes the numbering Add an item to the list and move the items up and down 3. checklists [/] • [ ] we can even have check lists • [ ] M-S-RET gives a new item with a check box • [ ] C-c C-c check/unchecks a box • [ ] you can have sub items • [ ] like this • [ ] that can be checked off individually • [ ] and you can track the number of items by adding [/] to the end of a line above a checklist - this updates when you check items off Add an item to the check list and check some items and sub-items off 4. definition lists definition lists these are useful sometimes word definition item 2 M-RET again gives another item, and long lines wrap in a tidy way underneath the definition Add an item to the definition list ### 4.2 org-mode tables Hopefully you can see straight away that the simple structure provided by org-mode gives a nice way to keep an electronic note book. Often it is nice to include tables in our notes - org handles this by using | to separate columns, and a line of — (inserted with C-c -) to add horizontal lines. You can create a blank table using M-x org-table-create and then entering the desired size Exercise: create an empty 4x4 table Now enter some stuff in your table. Use TAB to move forward a cell and S-TAB to move back a cell. Enter the following table, noticing how the columns changing width as needed ID X Y comments a 2 4 blah b 3 9 blah blah blah c 4 16 blah Now, you can move rows and columns around using M-arrow and insert or delete rows and columns using M-S-arrow. Try moving and inserting and deleting rows and columns #### 4.2.1 Advanced tables 1. creating and exporting You can easily convert some text to a table - select the following text and use C-c | to convert the region to a table ID x y A 2 4 B 3 9 C 4 16 D 5 25 You can also save tables to files by putting the cursor in the table and using M-x org-table-export 2. formulae You can use formulae to do arithmetic on tables (e.g. sum a column) and other spreadsheet-like functions - see the org manual for details ### 4.3 org-mode 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 your home directory. Do this by putting the cursor in the following code block and hitting C-c C-c (you may need to say yes to allow the code to run) (url-copy-file "http://www.star.bris.ac.uk/bjm/superman_cluster.png" (expand-file-name "~/superman_cluster.png") 1)  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 add a link here Since the file we have linked to is an image, we can display the image in emacs using C-c C-x C-v and use the same command to turn the image off again - try this. The structure of a link in org mode looks like this [[link address][text]]  where the link address is the URL or file name, and the text is the text that is displayed, so we can replace our superman link with something tidier like use C-u C-c C-l to add a link named "this" to the image here but note that this will not display when we turn on images. Links to other parts of the org file are added easily using the name of a section, like this [[org-mode structure][this link]]  Type this in to make a link to the earlier section Finally, we can add a caption and a name to our image like this which means we can refer to our image later by using the name we just gave it, for example, look at my picture in Fig. 1 ### 4.4 Formatting text Later on we'll look at exporting our org document to different formats. Org does this very nicely, and translates your text and markup appropriately. There are simple things you can do like italics bold text underlines literal text and strike through that org understands. Type a few examples here ### 4.5 LaTeX and source code blocks Sometimes you don't want org mode to try to do anything clever with some text and just display it as plain text. One way to do this is to use an example block. Go to a new line and type <e then press TAB [[link]]  Add an example block here Org understands simple latex syntax like superscripts x2 or symbols α β γ. Org can also cope with inline equations $$a=\sqrt{b^2+c^2}$$ or separate equations like this \begin{align} x^2 + \left(\frac{y}{z}\right)^4 = 0 \end{align} We'll see how these look when we export this file later. 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 tall 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. Now move the cursor inside the block and type C-c ' which will 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 Add a shell source code block here, containing the following lines (without the example tags) echo "HelloUSER! Today is date"
exit


It is possible to have org execute the code in a block by putting the cursor in there and using C-c C-c and then giving it permission when asked. By default the output of the code is added to the org file below the code block. You might need to say "y" when asked to confirm you want to execute the block.

Try this with the example code above.

This feature of org (called babel) is particularly powerful. There are much more sophisticated things you can do, like have the code read data from a table elsewhere in the file and add images to the file. You can also add links to line numbers in the code and more. See the org-mode and babel online documentation for more.

Here is an example where executing this shell code block generates a table

ls -Ss /homeb/bjm/docs | head -7 | grep -v total
exit


which is then used as an input for this R code block (using the :var option) to make a plot (if you have R installed)…

pie(files[,1], labels = files[,2])


### 4.6 Tangling your code for literate programming

In org mode you can "tangle" your file to extract out your code blocks into one or more file. This makes it a good way to document your code. As a trivial example, I want to write a script that will write the names of all of the files in my home directory to a file

ls ~/* > /tmp/aaa


then I want my script to count the number of lines in that file

wc -l /tmp/aaa


If I use C-c C-v C-t org will tangle those two code blocks into a file called filenames.sh

This can be a very good way of writing and documenting code - you can effectively write a manual and your code together and then tangle the code out into a file that you can compile or run.

Try tangling the script above then open filenames.sh to view the result

### 4.7 Org mode exporting

One strength of org-mode is the ability to export to multiple formats. Most useful are web pages and pdf (via latex). To export this 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.

Export this file to a web page and view it

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.

Export this file to pdf and view it

You can control which parts of the file are exported by adding tags to section headings. To do this, put the cursor on a heading and hit C-c C-c which will pop up a menu to select tags. Select the noexport tag and that heading will not be exported. Select the export tag and only that heading (and any other headings tagged with export) will be exported. Tags are inherited by subheadings.

Tag a heading as export and then export the file again

It is possible to add many customisations to the export process. Go to the top of the buffer (using M-<) and you can see some of the options that are used for this file. These are fine for simple pdf and html export, but see the org manual on exporting for more details.

### 4.8 Reproducible research

Using the techniques here, it is possible to create a single org document that contains all of the code and notes for a project, and also the draft and final versions of the paper. This makes it extremely easy for anyone to reproduce your work.

As an example, you can download the org file for a recent paper of mine here. That file doesn't contain all of the data (some of the data files were large), but does contain the code, results, code to generate plots, notes to myself, draft paper and final paper. By using the appropriate export settings at the top of the file I can export this to a latex file and pdf ready to submit to a journal.

## 5 Organising yourself with org-capture

Org mode has a very powerful way of managing todo lists including clocking the length of time spent on tasks and adding deadlines etc. I've given you a basic setup, but see this page for a really detailed example.

At the heart of this is org-capture. From anywhere in emacs hit C-c c t to capture a thought, link, or to-do item and then get right back to what you were doing.

Hitting C-c c t will pop up a small window with a template for an todo item that looks like an org-mode headline. You'll see it has a priority (B by default), a scheduled date (today by default), and a link to the current file. Add some text to the headline to make your item, and then you can customise it by

• using S-<up> and S-<down> to change the priority
• putting the cursor in the date field and using shift and arrow keys to change the date
• use C-c C-d to add a deadline date which will pop up a mini calendar - use shift and arrow keys to select the date. You can use C-c C-s to add a scheduled date, but we have one of those already by default.

When you are happy, use C-c C-c to save this item to a file (this defaults to todo.org in your home directory). The nice thing about this method of adding items (called org-capture) is that you can use it anywhere in Emacs and carry on with what you were doing.

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. My favourite is to use n in the dispatcher (i.e. use C-c a n) to view the current fortnight of scheduled tasks followed by the list of any unscheduled tasks. This switches to the agenda buffer. In this list view, you might want to:

&printdatnew("date2 = $date2 # date of o2\n");  Finally, you can use C-S and click the mouse button to add cursors anywhere with the mouse. ### 6.15 Paste history Copy some text (M-w) and then paste (C-y) and then use M-y to cycle through previously copied text. ### 6.16 Jump to previous positions Do a search (C-s) somewhere in the buffer and then press RET to finish the search. Now use C-u C-SPACE to jump back to where you started the search. Keep pressing C-SPACE to jump to previous locations. Emacs marks points in the text for lots of reasons (searching, copying, pasting etc) so this will usually take you somewhere useful. ### 6.17 Undo tree Type some text and then use C-z to undo some of the typing and type something else instead. In a normal editor pressing undo won't get you back to the original text that you previously undid. In Emacs you can use C-x u to start undo-tree-visualise to give you a diagram of your undo history that you can move through to get back to the earlier text. ### 6.18 Compare files with ediff To compare the contents of two text files, use M-x ediff-files and open the two files you want to compare. Stretch your window nice and wide so you can see both files side by side clearly. You should see blocks of text that differ between the two buffers highlighted. Press n to move to the next difference and p to move to the previous difference. Press a to copy the text from the left-hand file to the right-hand file, or press b to copy text from the right-hand file to the left-hand file. Press q to exit ediff and then save your files if you have modified them. ### 6.19 Quick calculation Use C-c b c to open a quick calculator in the minibuffer. Type a calculation and hit return to see the result. The nice thing is that the result is automatically added to the clipboard to be pasted into your work. ### 6.20 Insert today's date Use C-c b d to insert today's date. ### 6.21 Insert a file name Use C-c b i to insert the name of a file. ### 6.22 Manage files with dired Emacs has a very powerful file manager called dired. Hit C-x j to jump to the current file in dired. In dired you can do all the normal file management tasks, but a really neat trick is using C-x C-q to make the dired buffer editable. You can now edit the file names like a normal buffer, using e.g. multiple cursors to rename multiple files. Amazingly this also extends to editing links. Once you have made your edits use C-c C-c to save them and exit writeable mode in dired. For more about dired, see my blog posts ## 7 Email in Emacs This is a more advanced topic and I'll direct the interested reader to my blog for posts on how I use mu4e and org-mode to manage my emails. For the moment, consider a quick example of turning an email into a todo item. ## 8 Version history Current version is$Revision: 1.2 $$Log: emacs_tutorial.org,v \$
Revision 1.2  2016/11/13 21:10:19  bjm
Summary: Improved text around org-capture.

Revision 1.1  2016/11/12 22:04:22  bjm
Initial revision


Created: 2017-10-25 Wed 09:28

Validate