From a47360083283a119df50a2643d3bfed3d7de8b1a Mon Sep 17 00:00:00 2001 From: Arnaud Legrand Date: Thu, 7 Feb 2019 10:38:55 +0100 Subject: [PATCH] Attempt an automatic org -> md conversion with pandoc to check whether gitlab's rendering is effective or not. --- module2/ressources/emacs_orgmode.md | 467 ++++++++++++++++++++++++++++ 1 file changed, 467 insertions(+) create mode 100644 module2/ressources/emacs_orgmode.md diff --git a/module2/ressources/emacs_orgmode.md b/module2/ressources/emacs_orgmode.md new file mode 100644 index 0000000..6c02bbb --- /dev/null +++ b/module2/ressources/emacs_orgmode.md @@ -0,0 +1,467 @@ +**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 +[three video tutorials of this +sequence](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4), +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 ["emacs and git" video tutorial available at +the same +place](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4). + +The next section provides information on how to install emacs. + +Table of Contents[]{.tag data-tag-name="TOC"} +============================================= + +- [Installing emacs, org-mode, ess, and + auctex.](#installing-emacs-org-mode-ess-and-auctex) + - [Linux (Debian, Ubuntu)](#linux-debian-ubuntu) + - [macOS](#macos) + - [Windows](#windows) + - [All platforms: pretty code in HTML + export](#all-platforms-pretty-code-in-html-export) +- [A simple "*reproducible research*" emacs configuration + ](#a-simple-reproducible-research-emacs-configuration-) + - [Step 0: Backup and download our + configuration](#step-0-backup-and-download-our-configuration) + - [Step 1: Prepare your journal](#step-1-prepare-your-journal) + - [Step 2: Set up Emacs + configuration](#step-2-set-up-emacs-configuration) + - [Step 3: Adapt the configuration to your specific needs if + required](#step-3-adapt-the-configuration-to-your-specific-needs-if-required) + - [Step 4: Check whether the installation is working or + not](#step-4-check-whether-the-installation-is-working-or-not) + - [Step 5: Open and play with your + journal:](#step-5-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, org-mode, ess, and auctex. +============================================ + +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). + +Today, the stable versions of the most common distributions provide +recent enough versions of emacs and org-mode: + +- Debian (stretch) ships with [emacs + 25.1](https://packages.debian.org/stretch/emacs25) and [org-mode + 9.0.3](https://packages.debian.org/stretch/org-mode) +- Ubuntu (bionic 18.04) ships with [emacs + 25.2](https://packages.ubuntu.com/bionic/emacs25) and [org-mode + 9.1.6](https://packages.ubuntu.com/bionic/org-mode) +- Ubuntu (artful 17.04) ships with [emacs + 25.2](https://packages.ubuntu.com/artful/emacs25) and [org-mode + 9.0.9](https://packages.ubuntu.com/artful/org-mode) + +If your distribution is older than this, well, it may be a good time for +upgrading... + +Simply run (as root): + +``` {.bash .rundoc-block rundoc-language="sh" rundoc-results="output" rundoc-exports="both"} +apt-get update ; apt-get install emacs25 org-mode ess r-base auctex +``` + +Then make sure you have a sufficiently recent version of emacs. + +``` {.bash .rundoc-block rundoc-language="sh" rundoc-results="output" rundoc-exports="both"} +emacs --version 2>&1 | head -n 1 +``` + +``` {.example} +GNU Emacs 25.2.2 +``` + +Likewise, you'll want to check you have a recent version of org-mode: + +``` {.bash .rundoc-block rundoc-language="sh" rundoc-results="output" rundoc-exports="both"} +emacs -batch --funcall "org-version" 2>&1 | grep version +``` + +``` {.example} +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. + +- **Option 1**: Install the `.dmg` file from [Vincent + Goulet](http://vgoulet.act.ulaval.ca/): + [](https://vigou3.gitlab.io/emacs-modified-macos/). + It ships with recent versions: + - Emacs 26.1 + - Org-mode 9.1.13 + - ESS 17.11 + + If you install this version of Emacs, or in fact any other version + of Emacs distributed as a clickable application in a `.dmg` file, + you must type the full path to the executable if you want to run + Emacs from a terminal. For example, if your clickable application is + at `/Applications/Emacs.app`, then the executable is at + `/Applications/Emacs.app/Contents/MacOS/Emacs` + +- **Option 2**: If you use [Homebrew](https://docs.brew.sh/), do the + following: + + ``` {.bash .rundoc-block rundoc-language="sh" rundoc-results="output" rundoc-exports="both"} + brew update + brew install emacs --with-cocoa + brew linkapps emacs + brew install wget + brew tap dunn/emacs + brew install auctex + brew tap brewsci/science + brew install ess + ``` + + This provides an `emacs` command for use from the command line, plus + a clickable application at `Cellar/emacs/26.1_1/Emacs.app` inside + your Homebrew directory. If you installed Homebrew at the default + location `/usr/local`, then this is + `/usr/local/Cellar/emacs/26.1_1/Emacs.app`. If you installed + Homebrew on an account with administrator privileges, you can add + + ``` {.bash .rundoc-block rundoc-language="sh" rundoc-results="output" rundoc-exports="both"} + brew linkapps emacs + ``` + + in order to make Emacs accessible directly from `/Applications`. + +Windows +------- + +Install the `.exe` file from [Vincent +Goulet](http://vgoulet.act.ulaval.ca/): +[](https://vigou3.gitlab.io/emacs-modified-windows/). +It ships with recent versions: + +- Emacs 26.1 +- Org-mode 9.1.13 +- ESS 17.11 + +### 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 +[here](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/). + +### Installing and configuring Matplotlib (graphic python library) + +Open an DOS console and type the following command: + +``` {.shell .rundoc-block rundoc-language="shell" rundoc-results="output" rundoc-exports="both"} +python -m pip install -U matplotlib +``` + +![](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: + +``` {.python .rundoc-block rundoc-language="python" rundoc-results="output" rundoc-exports="both"} +import matplotlib +matplotlib.matplotlib_fname() +``` + +![](emacs_orgmode_images/matplotlib.png) + +Open the `matplotlibrc` file and modify the line starting with `backend` +to make it `backend : Agg`. + +All platforms: pretty code in HTML export +----------------------------------------- + +To have code pretty printing when exporting to HTML, you should install +the `htmlize` package, which is done by opening emacs and typing the +following command: + +``` {.example} +M-x package-install RET htmlize RET # where M-x means pressing the "Esc" key then the "x" key +``` + +A simple "*reproducible research*" emacs configuration +====================================================== + +This section is illustrated in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +(/"Mise en place Emacs/Orgmode"/ in French). Watching it before +following the instructions given in this section may help. + +Emacs comes with very basic default configuration and it appears like +everyone has its own taste. You will for example find +[here](https://www.emacswiki.org/emacs/StarterKits) 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](https://orgmode.org/worg/org-configs/index.html) for more +references). In the context of this MOOC, we propose you a relatively +minimalist one that is rather "*reproducible research*" oriented by +adding a few org-mode specific configurations. + +Step 0: Backup and download our configuration +--------------------------------------------- + +The procedure we propose will wipe your already existing custom Emacs +configuration if you have one. **You should thus beforehand make a +backup** of `~/.emacs` and of `~/.emacs.d/init.el` (if these files +exist). + +Then download [this +archive](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/raw/master/module2/ressources/rr_org_archive.tgz) +and uncompress it. It contains the following files and we will refer to +them in the following: + +``` {.example} +rr_org/init.el +rr_org/journal.org +``` + +Alternatively, [the files you are looking for are available +here](rr_org/). + +Step 1: Prepare your journal +---------------------------- + +Create an `org/` directory in the top of your home: + +``` {.bash .rundoc-block rundoc-language="sh" rundoc-results="output" rundoc-exports="both"} +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](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) +that you should give a try. + +Step 2: Set up Emacs configuration +---------------------------------- + +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`. + +Step 3: 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 4: Check whether the installation is working or not +-------------------------------------------------------- + +Open a new instance of Emacs and open a `foo.org` file. Copy the +following lines in this file: + +``` {.example} +#+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 [first entry of your +labbook](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org). + +Step 5: Open and play with your journal: +---------------------------------------- + +In step 1, you were told to create an journal in `~org/journal.org`. +First 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 FUN forums. + +A stub of a replicable article +============================== + +This section is illustrated in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +(/"Écrire un article réplicable avec Emacs/Orgmode"/ in French). +Watching it before following the instructions given in this section may +help. + +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](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org)) +and understand how it works though. + +Download the following +[archive](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/raw/master/module2/ressources/replicable_article.tgz), +uncompress it and simply `make` to generate the article. You should then +be able to open the [resulting +article](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf). +This is summarized in the following command: + +``` {.bash .rundoc-block rundoc-language="sh" rundoc-results="output" rundoc-exports="both"} +wget --no-check-certificate -O replicable_article.tgz https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/raw/master/module2/ressources/replicable_article.tgz +tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf +``` + +**Possible issues**: + +- 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: + + ``` {.bash .rundoc-block rundoc-language="sh" rundoc-results="output" rundoc-exports="both"} + 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 re-executing all the source code +when exporting, just look for the following line in +[article.org](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org): + +``` {.example} +# #+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. + +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 + +- [Common and step-by-step Emacs shortcuts for our *reproducible + research* + configuration](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) +- [The official GNU emacs + refcard](https://www.gnu.org/software/emacs/refcards/pdf/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) + and on + ![](http://sachachua.com/blog/wp-content/uploads/2013/08/20130830-Emacs-Newbie-How-to-Learn-Emacs-Keyboard-Shortcuts.png). + +### Org-mode + +- [Common and step-by-step org-mode shortcuts for our *reproducible + research* + configuration](https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org) +- [The official org-mode + refcard](https://orgmode.org/worg/orgcard.html) +- [The official description of the org-mode + syntax](https://orgmode.org/worg/dev/org-syntax.html) and a + [relatively concise description of the org-mode + syntax](https://gist.github.com/hoeltgman/3825415). + +Video tutorials +--------------- + +For those of you who prefer video explanations, here is a [Youtube +channel with many step by step emacs +tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg). + +Additional useful emacs packages +-------------------------------- + +### Company-mode + +[Company-mode](http://company-mode.github.io/) 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/) + +### Magit + +[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is +briefly illustrated in the context of this MOOC in a [video +tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4) +("*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 [this visual +walk-through](https://magit.vc/screenshots/) or [this really short +"crash course"](https://www.emacswiki.org/emacs/Magit). If you installed +the previous "*reproducible research*" emacs configuration, you can +easily invoke magit by using `C-x g`. + +Other resources +--------------- + +- [The compact Org-mode Guide](https://orgmode.org/orgguide.pdf) +- [Many examples illustrating the use of different languages in + org-mode](https://github.com/dfeich/org-babel-examples) + -- 2.18.1