# -*- mode: org -*- #+TITLE: Emacs/org-mode #+DATE: June, 2018 #+STARTUP: overview indent #+OPTIONS: num:nil toc:t #+PROPERTY: header-args :eval never-export *Disclaimer:* The two sections /A simple "reproducible research" emacs configuration/ and /A stub of replicable article/ explain how to set up emacs/org-mode for this MOOC. These are very important sections in the context of this MOOC. *These sections are illustrated in two out of the [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4][three video tutorials of this sequence]], and* *which you really should follow carefully*. *Otherwise, you may have trouble doing the exercises later on*. Likewise, I strongly encourage you to watch the [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4]["emacs and git" video tutorial available at the same place]]. The next section provides information on how to install emacs. * Table of Contents :TOC: - [[#installing-emacs][Installing Emacs]] - [[#linux-debian-ubuntu][Linux (Debian, Ubuntu)]] - [[#macos][macOS]] - [[#windows][Windows]] - [[#a-simple-reproducible-research-emacs-configuration][A simple "reproducible research" emacs configuration]] - [[#step-0-backup-and-remove-your-previous-configuration][Step 0: Backup and remove your previous configuration]] - [[#step-1-download-our-configuration][Step 1: Download our configuration]] - [[#step-2-prepare-your-journal][Step 2: Prepare your journal]] - [[#step-3-put-the-emacs-configuration-file-in-the-right-place][Step 3: Put the Emacs configuration file in the right place]] - [[#step-4-adapt-the-configuration-to-your-specific-needs-if-required][Step 4: Adapt the configuration to your specific needs if required]] - [[#step-5-check-whether-the-installation-is-working-or-not][Step 5: Check whether the installation is working or not]] - [[#step-6-open-and-play-with-your-journal][Step 6: Open and play with your journal:]] - [[#a-stub-of-a-replicable-article][A stub of a replicable article]] - [[#emacs-tips-and-tricks][Emacs tips and tricks]] - [[#cheat-sheets][Cheat-sheets]] - [[#video-tutorials][Video tutorials]] - [[#additional-useful-emacs-packages][Additional useful emacs packages]] - [[#other-resources][Other resources]] * Installing Emacs In the following we describe for each platform the installation method that we consider most convenient. There are other options that may be preferable in particular situations, so you may want to look at the [[https://www.gnu.org/software/emacs/download.html][Emacs Web site]] for details, but we strongly suggest you first try the method we recommend. At the end of the installation procedure, you should have one of 1. Emacs 26 (the latest version) 2. Emacs 25 plus Org-Mode 9 Emacs 25 comes with Org-Mode 8, which is not compatible with our examples. So if you use Emacs 25, you must separately install Org-Mode 9. Emacs 26 already includes Org-Mode 9. Our MOOC also requires a few extra Emacs packages: [[https://ess.r-project.org/][ESS]] (for working with the R language) and [[https://www.gnu.org/software/auctex/][AUCTeX]] (for editing LaTeX). They will be installed automatically the first time you start Emacs if you use the configuration described under [[#a-simple-reproducible-research-emacs-configuration][A simple "reproducible research" emacs configuration]]. ** Linux (Debian, Ubuntu) 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). These are the versions of Emacs that various distributions provide: - Debian (stretch) ships with [[https://packages.debian.org/stretch/emacs25][emacs 25.1]] and [[https://packages.debian.org/stretch/org-mode][org-mode 9.0.3]] - Ubuntu (bionic 18.04) ships with [[https://packages.ubuntu.com/bionic/emacs25][emacs 25.2]] and [[https://packages.ubuntu.com/bionic/org-mode][org-mode 9.1.6]] - Ubuntu (artful 17.04) ships with [[https://packages.ubuntu.com/artful/emacs25][emacs 25.2]] and [[https://packages.ubuntu.com/artful/org-mode][org-mode 9.0.9]] If your distribution is older than this, well, it may be a good time for upgrading... Simply run (as root): #+begin_src sh :results output :exports both apt-get update ; apt-get install emacs25 org-mode #+end_src Then verify that you have a sufficiently recent version of Emacs. #+begin_src sh :results output :exports both emacs --version 2>&1 | head -n 1 #+end_src #+RESULTS: : GNU Emacs 25.2.2 Likewise, you'll want to check you have a recent version of Org-Mode: #+begin_src sh :results output :exports both emacs -batch --funcall "org-version" 2>&1 | grep version #+end_src #+RESULTS: : 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. ** macOS *Note:* macOS comes with a prehistoric command-line-only version of Emacs located at =/usr/bin/emacs=. It's best to forget about it. The Web site https://emacsformacosx.com/ proposes precompiled Emacs versions for macOS. Download the latest version (the one that figures prominently on the page) and install it like you would install any other macOS application, by copying =Emacs.app= from the downloaded disk image to a convenient location on your computer. If you like working in a terminal (the =Terminal.app= from macOS, or an enhanced one such as [[https://iterm2.com/][iTerm2]]), the standard macOS way of opening a file in Emacs is =open -a Emacs.app /path/to/my/file.txt=. This will launch Emacs, unless it is already running, and then ask Emacs to open the file. Note that this is different from the Unix/Linux way of running Emacs, which is what you see in the videos. Under Linux, you type "emacs /path/to/my/file.txt" in the terminal, which always starts a fresh copy of Emacs. *** Advanced topics - not required for following the MOOC For advanced uses of Emacs, such as calling Emacs from a Makefile to automate document processing, you have to adopt the Unix way also under macOS, because this is the only way to provide parameters other than filenames. However, you have to enter the full path to the executable. Assuming that you have copied =Emacs.app= to =/path/to/emacs=, this is =/path/to/emacs/Emacs.app/Contents/MacOS/Emacs=. If you just type =emacs=, you will use the prehistoric command-line-only version at =/usr/bin/emacs= provided by Apple. You can of course make the Emacs executable more easily accessible using a shell alias, or by putting =/path/to/emacs/Emacs.app/Contents/MacOS/= on your =$PATH=. See the [[https://www.gnu.org/software/bash/manual/bashref.html][bash manual]] for details and explanation. Be aware that running Emacs the Unix way implies some subtle differences compared to running Emacs the macOS way. In particular, Emacs will inherit the shell's environment variables when run the Unix way, but the user session's environment variables when run the macOS way. ** Windows Download the [[https://ftp.gnu.org/gnu/emacs/windows/emacs-26/emacs-26.1-i686.zip][precompiled Emacs 26.1]] and unzip the zip file preserving the directory structure, and run =bin\runemacs.exe=. Alternatively, create a desktop shortcut to =bin\runemacs.exe=, and start Emacs by double-clicking on that shortcut's icon. See [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Windows-Startup.html][here]] for an explanation of this and other methods for launching Emacs under Windows. *** Directory naming conventions In the following instructions, we refer to your home directory through the (UNIX) =~/= notation. On Windows, your home directory should be something like =C:\Users\yourname=. Therefore, whenever we mention the =~/org/= (resp. the =~/.emacs.d/=) directory this means we are referring to =C:\Users\yourname\org= (resp. =C:\Users\yourname\.emacs.d\=). *** Making R and Python available to the console When running a command, Windows will look for the command in the directories indicated in the =PATH= environment variable. If none of these directories contains the command, Windows will stop and indicate the command does not exist. To make sure R (which may be in something like =C:/Program Files/R/R-3.5.1/bin/x64/=) and Python (which may be in something like =C:/Program Files/Python/Python37/=) can easily be run from Emacs, you should thus configure the =PATH= variable accordingly. This requires to go through the "Environment Variable" editor as explained [[http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/][here]]. *** Installing and configuring Matplotlib (graphic python library) Open an DOS console and type the following command: #+begin_src shell :results output :exports both python -m pip install -U matplotlib #+end_src [[file:emacs_orgmode_images/install_matplotlib.png]] Then you will want to deactivate interactive plots in matplotlib. To this end, you first need to know where the matplotlib configuration is located. Open a python console the type the following code: #+begin_src python :results output :exports both import matplotlib matplotlib.matplotlib_fname() #+end_src [[file:emacs_orgmode_images/matplotlib.png]] Open the =matplotlibrc= file and modify the line starting with =backend= to make it =backend : Agg=. * Python and R Computational documents contain code, which in the case of our MOOC use the languages Python and R. So you must install Python and R in addition to Emacs, unless of course they are already installed on your computer. Note that when we say Python, we mean the Python 3 language, not its predecessors Python 1 and Python 2, which are similar but not quite compatible. More precisely, the examples in the MOOC require Python 3.6 or later, the current official version being 3.7.3. For R, we have used version 3.4, but somewhat older versions are probably fine as well. Like for Emacs, there are many ways to install Python and R. Worse, there are good reasons for there being many ways, because there is no single best one for everybody. The following guidelines should help you pick a good one for you. *Linux users* should start by checking the packages provided by their Linux distribution. It almost certainly contains Python and R, but the versions may not be sufficiently recent. For example, Debian 9 (named "stretch"), the current stable release, proposes Python 3.5. The exact names of the packages you need to install unfortunately varies among distributions, but they should be similar to =python3= and =r-base=. *macOS* users who already use one of the package managers for macOS, i.e. one of [[https://brew.sh/][Homebrew]], [[https://www.macports.org/][MacPorts]], or [[http://www.finkproject.org/][fink]], should also look for Python and R in their distributions. However, it's not worth installing any of these package managers just for Python and R. Users of *Windows*, as well as *Linux* and *macOS* users who don't find sufficiently recent versions in their package manager's distributions, should consider the [[https://www.anaconda.com/distribution/][Anaconda distribution]] that contains both Python and R plus a huge collection of add-on packages for both languages. Anaconda is particularly recommended for those who plan to use Python more regularly, as it is the most convenient approach to managing Python environments. Finally, you can follow the installation procedures proposed by the development teams of [[https://www.python.org/][Python]] and [[https://www.r-project.org/][R]] for their respective languages. Compared to the approaches described above, the main inconvenience is the absence of simple strategies for updating and for installing add-on packages. But if you install Python and/or R just for the MOOC, this is not much of an issue. * LaTeX (optional) If you want to work with the replicable article stub (shown in [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4][this video]]), you also need an installation of LaTeX. This is a rather big piece of software (several GB), so you may prefer to skip its installation. It is not required to follow the MOOC, but if you end up producing real-life computational documents with Emacs, you will have to install it eventually. As for Python and R, *Linux* users, and also *macOS* users with a package manager, should start by checking their distribution's package list for packages called =tex=, =latex=, or better yet =texlive= or =miktex=, the two main TeX distributions that already contain almost everything you are likely to need. Otherwise, pick one of [[https://tug.org/texlive/][TeX Live]] or [[https://miktex.org/][MiKTeX]] and follow the installation instructions they provide. [[https://www.tug.org/mactex/][MacTeX]] for macOS is TeX Live plus a few macOS-specific add-ons. The differences between MiKTeX and TeX Live are not very important, so if you don't know which one to pick, toss a coin! * A simple "reproducible research" emacs configuration This section is illustrated in a [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4][video tutorial]] (/"Mise en place Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help. Emacs comes with a very basic default configuration, so almost everyone wants to personalize it. Given the flexibility of Emacs, a configuration can become quite complex and in fact include what would otherwise be considered complete software packages. In the context of this MOOC, we propose a relatively minimalist configuration oriented towards "/reproducible research/" with Org-Mode. If you are new to Emacs, we strongly recommended that you use it with as little modification as possible, by following the instructions in this section. If you are a more experienced Emacs user, you can go through the instructions and adopt the pieces that you consider useful for you. It is unfortunately rather probable that some of you will run into unforeseen problems with this configuration. If that is your case, ask a question on the forum. We will do our best to help you. ** Step 0: Backup and remove your previous configuration If you have used Emacs before, you may already have a personal configuration. And even if not, you may have Emacs configuration files without being aware of them, since some software packages create or modify Emacs configuration files. In order to avoid trouble, remove prior configurations, after making a backup elsewhere. The files that you should backup and then remove (if they exist) are: 1. =~/.emacs= 2. =~/.emacs.el= 3. =~/.emacs.elc= There is also a directory that you should backup and then remove (if it exists), with everything it might contain: 4. =~/.emacs.d= In the above filenames, =~/= stands for your home directory. Windows users should replace it by =C:\Users\MyName=, replacing MyName by their user name. ** Step 1: Download our configuration #+begin_src shell :results output :exports none export FILE_LIST="rr_org/init.el rr_org/journal.org rr_org/init.org" tar zcf rr_org_archive.tgz $FILE_LIST #+end_src Download [[file:rr_org_archive.tgz][this archive]] and uncompress it. It contains the following files and we will refer to them in the following: #+begin_src shell :results output :exports results tar tzf rr_org_archive.tgz #+end_src #+RESULTS: : rr_org/init.el : rr_org/journal.org : rr_org/init.org Alternatively, [[file:rr_org/][the files you are looking for are available here]]. As you may notice, the configuration (=init.el= in emacs lisp) is hard to follow, which is why we manage it through an =init.org=, file, which is really nice for readability. This is a trick you may want to adopt too (i.e., modify the =init.org= and regenerate the =init.el= by simply /tangling/ the file --with =M-x org-babel-tangle=, see instructions in the beginning of =init.org=). If you use Windows, and if you use a desktop shortcut to start Emacs, you must include the path to the file =init.el= in the command for the shortcut. For example, if you installed Emacs as =C:\Users\MyName/emacs=, your desktop shortcut should execute the command =C:\Users\MyName\emacs\bin\runemacs.exe -l .emacs.d/init.el=. ** Step 2: Prepare your journal Create an =org/= directory in the top of your home: #+begin_src sh :results output :exports both mkdir -p ~/org/ #+end_src 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 [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org][many Emacs shortcuts]] that you should give a try. ** Step 3: Put the Emacs configuration file in the right place Create the directory =~/.emacs.d/= and copy =rr_org/init.el= into it. ** Step 4: Adapt the configuration to your specific needs if required There are two situations in which it might be necessary to modify =init.el=: 1. Your network environment forces you to use a proxy for access to Web sites (HTTP(S) protocol). 2. You have multiple installations of Python or R on your computer, or they are in unusual places and not fully configured. If you can run - "python3" and "R" under Linux and macOS - "Python" and "R" under Windows in a terminal without getting an error message, then you should not have to do anything. If you do have to modify =init.el=, check the comments at the beginning of the file for instructions. ** Step 5: Check whether the installation is working or not Quit Emacs if it is running, and start it again. This first start will take a bit of time because Emacs will download a few add-on packages. For that reason, please make sure that you have a working internet connection for this step. Note also that the download can fail for other reasons, such as the package servers being overloaded. Such situations do not last very long, so we recommend that you just quit Emacs (=C-x C-c=, meaning =Ctrl + x= followed by =Ctrl + c=) and restart it. At worst, repeat this until you get no more errors on startup. Next, create a file =foo.org=. Copy the following lines into this file: : #+begin_src shell :session foo :results output :exports both : ls -la # or dir under windows : #+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 [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org][first entry of your labbook]]. ** Step 6: Open and play with your journal: In step 2, you were told to create a journal in =~org/journal.org=. You probably want to make sure this file is stored in a version control system like git. We leave it up to you to set this up but if you have any trouble, feel free to ask on the MOOC forum. * A stub of a replicable article This section is illustrated in a [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4][video tutorial]] (/"Écrire un article réplicable avec Emacs/Orgmode"/ in French). Watching it before following the instructions given in this section may help. To work with this article stub, you need working installations of LaTeX, R, and Python. If you can't open a terminal and run the commands =R=, =pdflatex=, and =python3=, you will not be able to generate this document. When being compiled, the article downloads the corresponding LaTeX packages, so you must have a working network connection. Note for macOS users: Since the article is compiled using =make=, you need to put the Emacs executable on your shell's search path, as explained above under [[*Advanced topics - not required for following the MOOC][advanced topics]]. #+begin_src shell :results output :exports none export FILE_LIST="replicable_article/Makefile replicable_article/article.org replicable_article/biblio.bib replicable_article/article.pdf" make -C replicable_article/ article.pdf tar zcf replicable_article.tgz $FILE_LIST #+end_src #+RESULTS: Download the following [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/raw/master/module2/ressources/replicable_article.tgz][archive]] and uncompress it. The archive contains the compiled article, so you can start by looking at it. To rebuild the article, delete =article.pdf=, or rename it to something else. Otherwise the rebuild procedure will simply tell you that the article is already up to date. Then type =make= to build everything from scratch. Open the freshly built =article.pdf= to see if it looks OK. If you get tired of always re-executing all the source code when exporting, look for the following line in [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org][article.org]]: #+BEGIN_EXAMPLE # #+PROPERTY: header-args :eval never-export #+END_EXAMPLE 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. * Emacs tips and tricks ** Cheat-sheets 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: *** Emacs - [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org][Common and step-by-step Emacs shortcuts for our /reproducible research/ configuration]] - [[https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf][The official GNU emacs refcard]] # French version: https://www.gnu.org/software/emacs/refcards/pdf/fr-refcard.pdf - Two graphical cheat-sheats by Sacha Chua on [[http://sachachua.com/blog/wp-content/uploads/2013/05/How-to-Learn-Emacs-v2-Large.png][how to learn Emacs]] and on [[http://sachachua.com/blog/wp-content/uploads/2013/08/20130830-Emacs-Newbie-How-to-Learn-Emacs-Keyboard-Shortcuts.png][how to learn Emacs shortcuts]]. *** Org-mode - [[https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org][Common and step-by-step org-mode shortcuts for our /reproducible research/ configuration]] - [[https://orgmode.org/worg/orgcard.html][The official org-mode refcard]] ([[https://www.gnu.org/software/emacs/refcards/pdf/orgcard.pdf][in pdf]]). - [[https://orgmode.org/worg/dev/org-syntax.html][The official description of the org-mode syntax]] and a [[https://gist.github.com/hoeltgman/3825415][relatively concise description of the org-mode syntax]]. ** Video tutorials For those of you who prefer video explanations, here is a [[https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg][Youtube channel with many step by step emacs tutorials]]. For general information about a number of packages you could also check the [[https://cestlaz.github.io/stories/emacs/][Using Emacs]], series of blogposts / videos. ** Additional useful emacs packages *** Company-mode [[http://company-mode.github.io/][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 Web page: [[http://company-mode.github.io/][http://company-mode.github.io/]] *** Magit [[https://magit.vc/][Magit]] is an Emacs interface for Git. Its usage is briefly illustrated in the context of this MOOC in a [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4][video tutorial]] ("/Utilisation Emacs/git/" in French). It is very powerful and we use it on a daily basis but you should definitely understand what git does behind the scenes beforehand. If you feel this would be useful for you, you should follow [[https://magit.vc/screenshots/][this visual walk-through]] or [[https://www.emacswiki.org/emacs/Magit][this really short "crash course"]]. If you installed the previous "/reproducible research/" emacs configuration, you can easily invoke magit by using ~C-x g~. ** Other resources - [[https://orgmode.org/orgguide.pdf][The compact Org-mode Guide]] - A huge ressource of emacs/org-mode magic is Bernt Hansen's «[[http://doc.norang.ca/org-mode.html][Organize your life in plain text]]», whose source is obviously itself an [[http://doc.norang.ca/org-mode.org][org-mode document]]. - [[https://github.com/dfeich/org-babel-examples][Many examples illustrating the use of different languages in org-mode]]