emacs_orgmode.org 24.8 KB
Newer Older
1
# -*- mode: org -*-
Arnaud Legrand's avatar
Arnaud Legrand committed
2
#+TITLE:     Emacs/Org-mode : trucs et astuces, Intallation et configuration
3
#+DATE: March 2019
4
#+STARTUP: overview indent
5
#+OPTIONS: num:nil toc:t
6 7
#+PROPERTY: header-args :eval never-export

8 9
This document provides information on how to install emacs.

Marie-Gabrielle Dondon's avatar
Marie-Gabrielle Dondon committed
10 11
*Disclaimer:* The two sections /A simple "reproducible research" emacs configuration/ 
and /A stub of replicable article/ explain how to set up
Arnaud Legrand's avatar
Arnaud Legrand committed
12 13
emacs/org-mode for this MOOC. These are very important sections in the
context of this MOOC. *These sections are illustrated in two
Laurence Farhi's avatar
Laurence Farhi committed
14
out of the [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4][three video tutorials of this page]], and* *which you
15 16
really should follow carefully*. *Otherwise, you may have trouble doing
the exercises later on*. Likewise, I strongly encourage you to watch
Laurence Farhi's avatar
Laurence Farhi committed
17
the [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4]["Use Emacs/git" video tutorial available at the same page]].
18

19
* Table of Contents                                                     :TOC:
Arnaud Legrand's avatar
Arnaud Legrand committed
20
- [[#installing-emacs][Installing Emacs]]
Arnaud Legrand's avatar
Arnaud Legrand committed
21 22 23
  - [[#linux-debian-ubuntu][Linux (Debian, Ubuntu)]]
  - [[#macos][macOS]]
  - [[#windows][Windows]]
24
- [[#python-r-and-latex][Python, R, and LaTeX]]
Arnaud Legrand's avatar
Arnaud Legrand committed
25
- [[#a-simple-reproducible-research-emacs-configuration][A simple "reproducible research" emacs configuration]]
Arnaud Legrand's avatar
Arnaud Legrand committed
26 27 28 29 30 31 32
  - [[#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:]]
Arnaud Legrand's avatar
Arnaud Legrand committed
33 34 35 36 37 38
- [[#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]]
39

40
* Installing Emacs
41 42 43
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
44 45 46 47

 1. Emacs 26 (the latest version)
 2. Emacs 25 plus Org-Mode 9

48
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.
49 50 51

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]].

52
** Linux (Debian, Ubuntu)
53
We provide here only instructions for Debian-based distributions. Feel
54
free to contribute to this document to provide up-to-date information
Arnaud Legrand's avatar
Arnaud Legrand committed
55
for other distributions (e.g. redhat, fedora).
56

57
These are the versions of Emacs that various distributions provide:
58 59 60 61 62 63 64 65
- 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
66
apt-get update ; apt-get install emacs25 org-mode
67 68
#+end_src

69
Then verify that you have a sufficiently recent version of Emacs.
70 71 72 73 74 75 76
#+begin_src sh :results output :exports both
emacs --version 2>&1 | head -n 1
#+end_src

#+RESULTS:
: GNU Emacs 25.2.2

77
Likewise, you'll want to check you have a recent version of Org-Mode:
78 79 80 81 82 83 84 85 86
#+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_,
87 88
which is now deprecated.

89
** macOS
Arnaud Legrand's avatar
Arnaud Legrand committed
90
*Note:* macOS comes with a prehistoric command-line-only version of Emacs located at =/usr/bin/emacs=. It's best to forget about it.
91

92 93
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.

Arnaud Legrand's avatar
Arnaud Legrand committed
94
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.
95

96
*** Advanced topics - not required for following the MOOC
Laurence Farhi's avatar
Laurence Farhi committed
97
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= in your =~/.bashrc= ou =~/.bash_profile=. See the [[https://www.gnu.org/software/bash/manual/bashref.html][bash manual]] for details and explanation.
98 99

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.
100
** Windows
Konrad Hinsen's avatar
Konrad Hinsen committed
101
Download the precompiled Emacs 26, which is available [[https://ftp.gnu.org/gnu/emacs/windows/emacs-26/emacs-26.1-i686.zip][for 32 bit architectures]]  or [[https://ftp.gnu.org/gnu/emacs/windows/emacs-26/emacs-26.1-x86_64.zip][for 64 bit architectures]]. The choice depends on your machine; if you don't know which is best, try the 64-bit version and if it cannot be started, switch to 32-bit. Unzip the zip file preserving the directory structure. If this approach does not work, follow the instructions from the [[https://www.gnu.org/software/emacs/download.html#windows][official emacs website]]. If this still fails, do not hesitate to ask questions on the forum.
102 103 104 105

Finally 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. You should be able to obtain a window that looks like this:
#+BEGIN_CENTER
[[file:emacs_orgmode_images/emacs.png]]
106

107 108
[[file:emacs_orgmode_images/scratch.png]]
#+END_CENTER
Arnaud Legrand's avatar
Arnaud Legrand committed
109
*** Directory naming conventions
110
In the following instructions, we refer to your home
Arnaud Legrand's avatar
Arnaud Legrand committed
111 112 113 114
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.
115 116 117
=C:\Users\yourname\.emacs.d\=). Note that the =C:\Users\yourname\.emacs.d\= directory should be automatically created when running emacs for the first time. This is where the emacs configuration will go.
*** Managing archives
Later in this document, you will be asked to download small archives containing files ([[file:rr_org_archive.tgz][rr_org_archive.tgz]] and [[file:replicable_article.tgz][replicable_article.tgz]]). To uncompress these archives on your computer, you may want to use the =7z= program. In this case, you may have to uncompress each file twice... The first time, =archive.tgz= will be uncompressed in =archive.tar= and the second time =archive.tar= will create a =archive/= directory comprising all the files of the original archive.
Arnaud Legrand's avatar
Arnaud Legrand committed
118
*** Making R and Python available to the console
119
When running a command, Windows will look for the command in the
Arnaud Legrand's avatar
Arnaud Legrand committed
120 121
directories indicated in the =PATH= environment variable. If none of
these directories contains the command, Windows will stop and indicate
122 123 124
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
Arnaud Legrand's avatar
Arnaud Legrand committed
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
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]]
Marie-Gabrielle Dondon's avatar
Marie-Gabrielle Dondon committed
144

145
Open the =matplotlibrc= file and modify the line starting with =backend=
Marie-Gabrielle Dondon's avatar
Marie-Gabrielle Dondon committed
146
to make it =backend : Agg=.
147

148
* Python, R, and LaTeX
149
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. Since Python and R are also used in the other paths of our MOOC, we explain their installation in a [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/19c2b1de7766484bae73f3ab133463c6][separate resource]].
150

Laurence Farhi's avatar
Laurence Farhi committed
151
That same resource also explains how to install LaTeX, which you must have if you want to produce PDF versions of org-mode documents. For example, 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#tuto3][the video "Write a replicable article with Emacs/Org-mode"]]), you must install LaTeX. However, it 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.
152

Arnaud Legrand's avatar
Arnaud Legrand committed
153
* A simple "reproducible research" emacs configuration 
154
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
Arnaud Legrand's avatar
Arnaud Legrand committed
155 156
Emacs/Orgmode"/ in French). Watching it before following the
instructions given in this section may help.
157

158 159 160
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
161 162
otherwise be considered complete software packages (see for example
these Emacs Starter Kits [[https://kieranhealy.org/resources/emacs-starter-kit/][here]] or [[https://www.emacswiki.org/emacs/StarterKits][here]]). In the context of
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195
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
196 197

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

202
Download [[file:rr_org_archive.tgz][this archive]] and uncompress it. It contains the
203 204 205 206 207 208 209 210 211
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
212 213 214 215
: 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
216
follow, which is why we manage it through an =init.org= file, which is
217 218 219 220
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=).
221

222 223 224
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
225
=C:\Users\MyName\emacs=, your desktop shortcut should execute the
226
command =C:\Users\MyName\emacs\bin\runemacs.exe -l .emacs.d/init.el=.
227

228
** Step 2: Prepare your journal
229 230
Create an =org/= directory in the top of your home:
#+begin_src sh :results output :exports both
231 232
mkdir -p ~/org/ 
# on Windows, use the file explorer to create the directory C:\Users\MyName\org
233 234 235 236
#+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
237
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
238
should give a try.
239 240 241
** 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
242 243 244 245 246 247 248
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 
Arnaud Legrand's avatar
Arnaud Legrand committed
249 250
      - =python3= and =R= under Linux and macOS
      - =Python= and =R= under Windows
251 252 253 254 255
   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.
256
** Step 5: Check whether the installation is working or not
257 258
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
259
packages. For that reason, please make sure that you have a working
260 261 262 263 264 265 266
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.

267
Next, create a file =foo.org=. Copy the following lines into this file:
268
   : #+begin_src shell :session foo :results output :exports both
Arnaud Legrand's avatar
Arnaud Legrand committed
269
   : ls -la # or dir under windows
270 271 272 273
   : #+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
274
commands, this one means '=Ctrl + c=' twice)
275 276 277 278 279 280 281

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
282
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]].
283 284 285
** 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
286
stored in a version control system like git. We leave it up to you
Arnaud Legrand's avatar
Arnaud Legrand committed
287
to set this up but if you have any trouble, feel free to ask on the
288
MOOC forum.
289
* A stub of a replicable article
Laurence Farhi's avatar
Laurence Farhi committed
290
This section is illustrated in a [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4#tuto3][video tutorial]] (/"Write a replicable article with Emacs/Org-mode"/). Watching it before
Arnaud Legrand's avatar
Arnaud Legrand committed
291
following the instructions given in this section may help.
292

293 294 295
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]].
296 297

#+begin_src shell :results output :exports none
298 299 300
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
301 302 303 304
#+end_src

#+RESULTS:

Arnaud Legrand's avatar
Arnaud Legrand committed
305
Download the following [[file:replicable_article.tgz][archive]] and uncompress it. The archive contains the compiled article, so you can start by looking at it.
306 307

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.
308

309
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]]:
310 311 312
#+BEGIN_EXAMPLE
# #+PROPERTY: header-args :eval never-export
#+END_EXAMPLE
313
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.
314

315
* Emacs tips and tricks
316
** Cheat-sheets
317
Learning Emacs and Org-Mode can be difficult as there is an inordinate
318 319 320
amount of shortcuts. Many people have thus come up with
cheat-sheats. Here is a selection in case it helps:
*** Emacs
321
- [[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]]
322 323
- [[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
324 325
- 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]].
326
*** Org-mode
327
- [[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]]
328
- [[https://orgmode.org/worg/orgcard.html][The official org-mode refcard]] ([[https://www.gnu.org/software/emacs/refcards/pdf/orgcard.pdf][in pdf]]).
329 330 331 332
- [[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]].
333 334 335

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.
336 337 338 339 340
** 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
Marie-Gabrielle Dondon's avatar
Marie-Gabrielle Dondon committed
341
official Web page: [[http://company-mode.github.io/][http://company-mode.github.io/]]
342
*** Magit
343
[[https://magit.vc/][Magit]] is an Emacs interface for Git. Its usage is briefly illustrated
344
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]] 
Marie-Gabrielle Dondon's avatar
Marie-Gabrielle Dondon committed
345
("/Utilisation Emacs/git/" in French).
346 347

It is very powerful and we use it on a daily basis but you should
348
definitely understand what git does behind the scenes beforehand. If
349
you feel this would be useful for you, you should follow [[https://magit.vc/screenshots/][this visual
350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375
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~.  Magit will
then prompt you for the path of your local clone of the git repository
(the path to mooc-rr in the context of this MOOC).
[[file:emacs_orgmode_images/git1.png]]

If you do not rely on our "/reproducible research/" emacs configuration,
you should have a look at [[https://magit.vc/manual/magit/Installing-from-an-Elpa-Archive.html][how to install magit from an ELPA archive]].

The following method has been tested with Windows and worked like a charm:
- Add the following piece of text in your =.emacs.d/init.el= file:
  #+begin_src emacs-lisp
  (require 'package)
  (add-to-list 'package-archives
               '("melpa" . "http://melpa.org/packages/") t)

  #+end_src
- Launch Emacs and run the following commands:
  #+BEGIN_EXAMPLE
  M-x package-refresh-contents RET
  M-x package-install RET magit RET
  #+END_EXAMPLE
  NB: =M-= corresponds to the =<Alt>= key and =RET= corresponds to the
  =<Return>= key.
376
** Other resources
Laurence Farhi's avatar
Laurence Farhi committed
377
- The compact Org-mode Guide ([[https://orgmode.org/orgguide.pdf][pdf file]])
378
- A huge resource of emacs/org-mode magic is Bernt Hansen's «[[http://doc.norang.ca/org-mode.html][Organize
379 380 381 382 383 384
  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]]