Disclaimer: The two sections A simple "reproducible research" emacs configuration and A stub of replicable article explain how to set up org-mode for this MOOC. You really should follow them carefully or you may have trouble doing the exercices later on.
The next sections provide information on how to install emacs. Before proceeding, make sure you have read the "Git and GitLab" instructions.
We provide here only instructions for debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g.n redhat, fedora).
Today, the stable versions of the most common distributions provide recent enough versions of emacs and org-mode:
If your distribution is older than this, well, it may be a good time for upgrading…
Simply run (as root):
apt-get update ; apt-get install emacs25 org-mode ess r-base auctex
Then make sure you have a sufficiently recent version of emacs.
emacs --version 2>&1 | head -n 1
GNU Emacs 25.2.2
Likewise, you'll want to check you have a recent version of org-mode:
emacs -batch --funcall "org-version" 2>&1 | grep version
Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/)
The version numbers you get will depend on the distribution you are running. You really want to make sure you do not rely on org-mode 8, which is now deprecated.
Option 1: Install the .dmg file from Vincent Goulet:
https://vigou3.github.io/emacs-modified-macos/. It ships with recent
versions:
In that case you may have several versions of emacs installed on your machine and launching emacs from a terminal may not run the one you just installed. If anyone know how to get rid of this…
Option 2: If you already use brew, simply do the following
brew update brew install emacs [--with-cocoa] brew linkapps emacs brew tap homebrew/science brew install ess brew install auctex # The name may be slightly more complicated here brew install wget
Install the .exe file from Vincent Goulet:
https://vigou3.github.io/emacs-modified-windows/. It ships with recent
versions:
There will be a mini video illustrating these steps at some point
Emacs comes with very basic default configuration and it appears like everyone has its own taste. You will for example find here several default Emacs configurations that reflect the preferences of their creators. Likewise the configuration of Org-Mode is incredibly flexible (see for example the org-mode website for more references). In the context of this MOOC, we propose you a relatively minimalistic one that is rather "reproducible research" oriented by adding a few org-mode specific configurations.
The procedure we propose will wipe your already existing custom emacs
configuration if you already have one. You should thus beforehand make
a backup of ~/.emacs and of ~/.emacs.d/init.el (if these file
exists).
Then download this archive and uncompress it. It contains the following files and we will refer to them in the following:
rr_org/init.el rr_org/journal.org
Create an org/ directory in the top of your home:
mkdir -p ~/org/
Then copy rr_org/journal.org file in your ~/org/ directory. This
file will be your laboratory notebook and all the notes you will
capture with C-c c will go automatically go in this file. The first
entry of this notebook is populated with many emacs shortcuts that you
should give a try.
Copy rr_org/init.el in your ~/.emacs.d/ directory.
Alternatively, if you do not want to mess with your already existing
emacs configuration, you may launch emacs with this specific
configuration with the following command: emacs -q -l rr_org/init.el.
Open a new instance of Emacs and open a foo.org file. Copy the
following lines in this file:
#+begin_src shell :session foo :results output :exports both ls -la #+end_src
Put your cursor inside this code block and execute it with the
following command: C-c C-c (If you are not familiar with Emacs
commands, this one means 'Ctrl + C' twice)
A #+RESULTS: block with the result of the command should appear if it
worked.
In the video, we already have demonstrated the main features and shortcuts of emacs/org-mode that will help you maintain a document and benefit from literate programming. The list of features and shortcuts is demonstrated in the first entry of your labbook.
In step 1, you were told to create an journal in
~org/journal.org. First you probably want to make sure this file is
backed up in a revision control system like git. We leave it up to set
this up but if you have any trouble, feel free to ask on the FUN
forums.
There will be a mini video illustrating these steps at some point
Remember, you need a working LaTeX and R environment. If you can't
open a terminal and run the commands R, pdflatex, and python, you will not be
able to generate this document. When being compiled, the article downloads the
corresponding LaTeX packages so you also need to have a working wget
command (alternatively, it uses curl). Once downloaded, you may still read the
source (article.org) and understand how it works though.
Download the following archive and untar it.
and simply make to generate the
article. You should then be able to open the resulting article. This
is summarized in the following command:
wget --no-check-certificate -O replicable.tgz https://github.com/alegrand/RR_webinars/raw/master/1_replicable_article_laboratory_notebook/replicable/replicable.tgz ### Fix the broken URL tar zxf replicable.tgz; cd replicable; make ; evince article.pdf
If the make command fails (especially on Mac), it may be because emacs
or something else is not correctly installed. In that case, open the
article directly with the following command:
emacs -q --eval "(setq enable-local-eval t)" --eval "(setq enable-local-variables t)" article.org
and export it to pdf with the following shortcut: C-c C-e l o
If it still doesn't work and emacs complains about not finding ESS, it
may be because you installed ESS in your home instead of
system-wide. In that case, try to remove the -q in the previous
command line to load your personal emacs configuration.
Finally, when you'll be tired of always reexecuting all the source code when exporting, just look for the following line in article.org:
# #+PROPERTY: header-args :eval never-export
If you remove the # in the beginning of the line, it will not be a
comment anymore and will indicate org-mode to stop evaluating every
chunk of code when exporting.
Learning emacs and org-mode can be difficult as there is an inordinate amount of shortcuts. Many people have thus come up with cheat-sheats. Here is a selection in case it helps:
For those of you who prefer video explanations, here is a Youtube channel with many step by step emacs tutorials.
Company-mode is a text completion framework for Emacs. It allows to have smart completion in emacs for the most common languages. If you feel this is needed, you should follow the instructions from the official webpage: http://company-mode.github.io/
Magit is an emacs interface for Git. It is very powerfull and we use it on a daily basis but you should definitely understand what git does behind the scene beforehand. If you feel this would be useful for you, you should follow the instructions from here: https://www.emacswiki.org/emacs/Magit
