# -*- mode: org -*-
#+TITLE:     Emacs/org-mode
#+AUTHOR:    Arnaud Legrand
#+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+session01bis/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+session01bis/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4]["emacs and git" video tutorial available at the same place]].

The next section provides information on how to install emacs.

* 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 [[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 ess r-base auctex
#+end_src

Then make sure 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. 
** Mac OS X
- *Option 1*: Install the =.dmg= file from [[http://vgoulet.act.ulaval.ca/][Vincent Goulet]]:
  https://vigou3.github.io/emacs-modified-macos/. It ships with recent
  versions:
  - Emacs 26.1
  - Org-mode 9.1.13
  - ESS 17.11
  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
  #+begin_src sh :results output :exports both
  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
  #+end_src
** Windows
Install the =.exe= file from [[http://vgoulet.act.ulaval.ca/][Vincent Goulet]]:
https://vigou3.github.io/emacs-modified-windows/. It ships with recent
versions:
- Emacs 26.1
- Org-mode 9.1.13
- ESS 17.11
* A simple "/reproducible research/" emacs configuration 
This section is illustrated in a [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/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 very basic default configuration and it appears like
everyone has its own taste. You will for example find [[https://www.emacswiki.org/emacs/StarterKits][here]] several
default Emacs configurations that reflect the preferences of their
creators. Likewise the configuration of Org-Mode is incredibly
flexible (see for example [[https://orgmode.org/worg/org-configs/index.html][the org-mode website]] 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 already have one. *You should thus beforehand make
a backup of =~/.emacs= and of =~/.emacs.d/init.el=* (if these file
exists).

#+begin_src shell :results output :exports none
export FILE_LIST="rr_org/init.el rr_org/journal.org"
tar zcf rr_org_archive.tgz $FILE_LIST
#+end_src

#+RESULTS:
Then download [[https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/raw/master/module2/ressources/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

** Step 1: 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://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org][many emacs shortcuts]] 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: 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:
   : #+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 [[https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org][first entry of your labbook]].
** Step 4: 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
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.
* A stub of replicable article
This section is illustrated in a [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/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.

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 ([[https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org][article.org]]) and understand how it works though.

#+begin_src shell :results output :exports none
make -C replicable_article/ all ../replicable_article.tgz
#+end_src

#+RESULTS:

Download the following [[https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/raw/master/module2/ressources/replicable_article.tgz][archive]], uncompress it and simply =make= to generate the
article. You should then be able to open the [[https://app-learninglab.inria.fr/gitlab/learning-lab/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf][resulting article]]. This
is summarized in the following command:
#+begin_src sh :results output :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
#+end_src

*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:
  #+begin_src sh :results output :exports both
  emacs -q --eval "(setq enable-local-eval t)" --eval "(setq enable-local-variables t)"  article.org
  #+end_src
  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 [[https://app-learninglab.inria.fr/gitlab/learning-lab/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://app-learninglab.inria.fr/gitlab/learning-lab/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]]
- Two graphical cheat-sheats by Sacha Hua 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://app-learninglab.inria.fr/gitlab/learning-lab/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://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]].
** 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/
*** 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+session01bis/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 scene 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]]
- [[https://github.com/dfeich/org-babel-examples][Many examples illustrating the use of different languages in org-mode]]
