Spread Marie-Gabrielle's documentation to the right places.

documents/tuto_emacs_windows/tuto_emacs_windows.md

-Table des matières
-=================
-- [1 Installation et configuration des différents outils](#1-installation-et-configuration-des-diff%C3%A9rents-outils)
-  - [1.1 Installer et configurer Emacs](#11-installer-et-configurer-emacs)
-  - [1.2 Ajouter les chemins de R et Python dans dans la variable PATH de Windows](#12-ajouter-les-chemins-de-r-et-python-dans-dans-la-variable-path-de-windows)
-  - [1.3 Installer et configurer matplotlib (librairie graphique Python)](#13-installer-et-configurer-matplotlib-librairie-graphique-python)
-- [2 Utilisation d'Emacs](#2-utilisation-demacs)
-  - [2.1 Exécuter des commandes dos](#21-exécuter-des-commandes-dos)
-  - [2.2 Exécuter du code R](#22-exécuter-du-code-r)
-  - [2.3 Exécuter du code Python](#23-exécuter-du-code-python)
-  - [2.4 Écrire dans le journal](#24-écrire-dans-le-journal)
-
-# 1 Installation et configuration des différents outils
-
-## 1.1 Installer et configurer Emacs
-
-- Installer [Emacs modifié pour Windows](https://vigou3.github.io/emacs-modified-windows/)
-  - version 26.1 pour Windows 64 bits
-  - version 25.2 pour Windows 32 bits
-  
-- Télécharger le fichier [rr_org_archive.tgz](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org_archive.tgz)
-
-*NB : Avec 7z il faut décompresser l'archive deux fois : une première fois crée une archive `rr_org_archive.tar` et une deuxième fois crée un dossier `rr_org` contenant les fichiers `init.el` et `journal.org`.*
-
-- Lancer Emacs
-
-![emacs](documents/tuto_emacs_windows/images/emacs.png)
-
-- Emacs crée le répertoire `C:\Users\***\.emacs.d`
-
-*NB : Le répertoire est créé au premier lancement d'Emacs.*
-
-- Placer le fichier `init.el` dedans
-
-- Lancer Emacs
-
-![scratch](documents/tuto_emacs_windows/images/scratch.png)
-
-- Exécuter la commande suivante pour installer `htmlize`
-
-```
-M-x package-install RET htmlize RET
-```
-
-- Créer un dossier `C:\Users\***\org` dans l'explorateur Windows
-
-- Placer le fichier `journal.org` dedans
-
----
-
-## 1.2 Ajouter les chemins de R et Python dans dans la variable PATH de Windows
-
-La façon de procéder est très bien expliquée [ici](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/).
-
----
-
-## 1.3 Installer et configurer matplotlib (librairie graphique Python)
-
-- Installer la librairie `matplotlib`
-
- - Ouvrir une invite de commande dos
- - Exécuter la commande suivante
-
-```
-python -m pip install -U matplotlib
-```
-
-![install_matplotlib](documents/tuto_emacs_windows/images/install_matplotlib.png)
-
-- Désactiver les plots interactifs dans matplotlib
-
-Pour ce faire, il faut d'abord savoir où se trouve le fichier de configuration de matplotlib sous Windows.
-
-Exécuter le code suivant sous Python
-
-```
-import matplotlib
-matplotlib.matplotlib_fname()
-```
-
-![matplotlib](documents/tuto_emacs_windows/images/matplotlib.png)
-
-Ouvrir le fichier `matplotlibrc` et ajouter un `#` devant la ligne qui commence par `backend`, ce qui correspond à utiliser la valeur par défaut `Agg`
-
----
-
-## 1.4 Installer MiKTeX
-
-Télécharger et installer [MiKTeX](https://miktex.org/download) en choisissant le bon système d'exploitation. 
-Vous serez amené à installer différents packages lors du premier export pdf.
-
----
----
-
-# 2 Utilisation d'Emacs
-
-## 2.1 Exécuter des commandes dos
-
-- Lancer Emacs
-
-- Créer un fichier toto.org dans l'explorateur Windows
-
-- Ouvrir le fichier toto.org dans Emacs et saisir `<b` + `tab`.
-
-![shell](documents/tuto_emacs_windows/images/shell.png)
-
-- Le raccourci `C-g` permet de sortir d'une commande
-
----
-
-## 2.2 Exécuter du code R
-
-- Le raccourci `<r` + `tab` permet d'exécuter une commande R
-
-![commandeR1](documents/tuto_emacs_windows/images/commandeR1.png)
-
-Emacs demande le dossier de démarrage. Garder le dossier par défaut (`Entrée`)
-
-![commandeR2](documents/tuto_emacs_windows/images/commandeR2.png)
-
-- Le raccourci `<R` + `tab` permet d'exécuter une commande graphique R
-
-(org-babel-temp-file \"figure\" \".png\") génère un nom de fichier temporaire.
-
-Il faut indiquer un nom de fichier pour que l'image soit chargée lors de la réouverture du fichier Emacs.
-
-![graphiqueR](documents/tuto_emacs_windows/images/graphiqueR.png)
-
-Remarque : Il peut être pratique de remplacer `(org-babel-temp-file \"figure\" \".png\")` par `"D:/temp/figure.png\"` dans dans le fichier `init.el` (raccourci `<R` et `<PP`).
-
----
-
-## 2.3 Exécuter du code Python
-
-- Voir la page [Python Source Code Blocks in Org Mode](https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-python.html)
-
-- Le raccourci `<p` + `tab` permet d'exécuter du code Python en mode "non-session"
-
-![python1](documents/tuto_emacs_windows/images/python1.png)
-
-- Le raccourci `<P` + `tab` permet d'exécuter du code Python en mode "session" pour conserver les valeurs d'un bloc de code à l'autre.
-
-![python2](documents/tuto_emacs_windows/images/python2.png)
-
-- Le raccourci `<PP` + `tab` permet d'exécuter un graphique Python
-
-![python4](documents/tuto_emacs_windows/images/python4.png)
-
-- Si cette commande échoue, essayer de mettre la librairie `numpy` à jour
-
-Exécuter le code suivant dans une invite de commande dos
-
-```
-python -m pip install -U numpy
-```
-
----
-
-## 2.4 Écrire dans le journal
-
-- Ouvrir le fichier `journal.org`
-
-- Le raccourci `C-c c` ouvre un menu demandant si on veut écrire dans la todo list ou dans le journal
-
-![ctrl_c_c](documents/tuto_emacs_windows/images/ctrl_c_c.png)
-
-- On appuie sur `j` pour écrire dans le journal. Un mini buffer est ouvert et Emacs modifie le fichier `journal.org` pour créer une entrée à la bonne date. On peut commencer à écrire dans le journal.
-
-![org_mode](documents/tuto_emacs_windows/images/org_mode.png)
-
-`C-c C-c` pour enregistrer les modifications.
-
-- La combinaison `Alt`+ `flèche gauche` ou `flèche droite` permet de décaler les puces à gauche ou à droite.
-
-- Penser à enregistrer avant de quitter !

html_src_files.lst

@@ -23,6 +23,8 @@
 ./module2/ressources/gitlab_fr.org               #     https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/448cd6f9018545d1a67405551add6fda
 ./module2/ressources/emacs_orgmode.org               #     https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/954f94ce4f9a4d858d47b41793cc96c8
 ./module2/ressources/emacs_orgmode_fr.org               #     https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/954f94ce4f9a4d858d47b41793cc96c8
+./module2/ressources/emacs_newbie.org               #     
+./module2/ressources/emacs_newbie_fr.org               #     
 ./module2/ressources/sequence6_examples/README.org               #     https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/827b36e10ddd49239f1c62cc1903951a
 ./module2/ressources/sequence6_examples/README_fr.org               #     https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/827b36e10ddd49239f1c62cc1903951a
 ./module2/ressources/python_r_latex.org               #     https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/19c2b1de7766484bae73f3ab133463c6
@@ -53,5 +55,4 @@
 ./module4/ressources/resources_environment_fr.org               #     https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/4be922aa6b8c471ab1addcdbddb4e487
 
 ./documents/notebooks/notebook_RStudio_SASmarkdown.md               #     
-./documents/tuto_emacs_windows/tuto_emacs_windows.md               #     
 ./documents/tuto_jupyter_windows/tuto_jupyter_windows.md               #     https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/512cf2f3bc844d88b3954a3748d01c0f

module2/ressources/emacs_newbie.org

+# -*- mode: org -*-
+#+TITLE:     First steps with Emacs/org-mode
+#+DATE: March 2019
+#+STARTUP: overview indent
+#+OPTIONS: num:nil toc:t
+#+PROPERTY: header-args :eval never-export
+
+
+This document assumes you have installed emacs as explained in
+FIXME. All the screenshots in this demo are done under the Windows
+operating system but it should look similar on any OS.
+
+* First steps with Emacs as a computationnal environment
+** Run Emacs
+- Launch emacs
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/emacs.png]]
+  #+END_CENTER
+- Create a new file using the "white sheet of paper" left icon, right
+  below the =File= menu. Name it =foo.org= in which ever directory you
+  want.
+** Running dos/shell commands
+- You now have a blank org-mode file.
+- Type =<b= and press the =tab= key to expend it as the beginning of a
+  shell block. You can then type whichever command you want (e.g., =dir=
+  under windows or =ls= under linux or Mac). By typing =C-c C-c= (this
+  means typing twice =Ctrl= =c=), your shell command should be executed
+  and the output should but put right below.
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/shell.png]]
+  #+END_CENTER
+
+- Whenever you feel emacs has entered a weird state and you want to
+  exit from this mode, press =C-g= (again, this reads as =Ctrl= =g=) several
+  times.
+** Running R code
+- Similarly to the abovementionned =<b= shortcut, the shortcut =<r= + =tab=
+  will allow you to create a block for running R commands (e.g.,
+  =summary(cars)=). Likewise, the code will be executed by typing =C-c
+  C-c= (typing twice =Ctrl= =c=)
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/commandeR1.png]]
+  #+END_CENTER
+  At this point, Emacs will prompt you to ask where R should be
+  launched. Simply keep the current directory by hitting the =Return=
+  key. Again, the output is captured and inserted right below.
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/commandeR2.png]]
+  #+END_CENTER
+
+- The =<R= + =tab= shortcut will allow you to run R commands that generate
+  graphics. The =(org-babel-temp-file \"figure\" \".png\")= generates a
+  temporary file name. It will thus be erased when closing emacs. If
+  you want the image to be persistant, indicate a real file name instead.
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/graphiqueR.png]]
+  #+END_CENTER
+
+  If you do not like this behavior, you can edit the =init.el= file and
+  replace =(org-babel-temp-file \"figure\" \".png\")= by
+  =\"D:/temp/figure.png\"= or whichever location/name you prefer (both
+  for =<R= et =<PP=).
+** Running python code
+- You may want to read the [[https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-python.html][Python Source Code Blocks in Org Mode]]
+  webpage for more examples
+
+- The =<p= + =tab= will insert a python block in a /non-session/ mode. This
+  means that a new python shell will be started for this block and
+  that variables will not be shared between blocks. Again, the code
+  is executed with the =C-c C-c= shortcut.
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/commande_python.png]]
+  #+END_CENTER
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/python1.png]]
+  #+END_CENTER
+  # Note that if python was not correctly installed, you may end up with
+  # a message like this:
+  # #+BEGIN_CENTER
+  # [[file:emacs_orgmode_images/python3.png]]
+  # #+END_CENTER
+  # Then try to follow the steps in the installation section.
+- The =<P= + =tab= will insert a python block in /session/ mode. This
+  allows to keep variables alive from a block to an other. Internally,
+  emacs will have a buffer with a python session running. Again, the
+  code is executed with the =C-c C-c= shortcut.
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/python2.png]]
+  #+END_CENTER
+
+- The =<PP= + =tab= will insert a python block in /session/ mode and ready
+  to generate graphics.
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/python4.png]]
+  #+END_CENTER
+  If this fails, try to update the python =numpy= library, for exemple
+  like this in a dos/shell command:
+  #+begin_src shell :results output :exports both
+  python -m pip install -U numpy
+  #+end_src
+* Taking notes with Emacs Org-Mode
+** What does it look like.
+- Open the =journal.org= file you have placed in the =~/org/=
+  directory. You will find a few first "old" entries with the most
+  useful emacs shortcuts, including the ones that have been presented
+  above.
+** Taking notes
+
+- The =C-c c= (=Ctrl c= then =c=) will open a menu asking you whether you
+  want to take notes in your todo list or in your journal.
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/ctrl_c_c.png]]
+  #+END_CENTER
+
+- Hit =j= to take notes in your journal.
+  Emacs then opens =journal.org= to create an entry with the right date
+  and presents you with a mini buffer in which you can start taking
+  notes.
+  #+BEGIN_CENTER
+  [[file:emacs_orgmode_images/org_mode.png]]
+  #+END_CENTER
+  When you are dones, simply hit =C-c C-c= to save your modifications
+  and close the mini-buffer.
+** Fast editing of an org document
+- It is common when taking notes in a brainstorming session to have to
+  clean and reorganize them. The =Alt= + =\leftarrow= or =Alt= +
+  =\rightarrow=  will allow you to shift items to the left or to the right.
+- Org-mode shortcuts are actually much more intuitive than prehistoric
+  emacs shortcuts. You'll quickly get use to it. Again, have a look to
+  the first entry of the =journal.org= file we gave you and which
+  contains many useful tips.
+- Do not forget to save your files before closing emacs! 

module2/ressources/emacs_newbie_fr.org

+# -*- mode: org -*-
+#+TITLE:     FIXME Premiers pas avec Emacs/org-mode
+#+DATE: March 2019
+#+STARTUP: overview indent
+#+OPTIONS: num:nil toc:t
+#+PROPERTY: header-args :eval never-export
+
+See the English version. French translation in progress.

module2/ressources/emacs_orgmode.org

@@ -5,6 +5,8 @@
 #+OPTIONS: num:nil toc:t
 #+PROPERTY: header-args :eval never-export
 
+This document provides information on how to install emacs.
+
 *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
@@ -14,15 +16,12 @@ 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]]
-- [[#python-and-r][Python and R]]
-- [[#latex-optional][LaTeX (optional)]]
+- [[#python-r-and-latex][Python, R, and LaTeX]]
 - [[#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]]
@@ -99,16 +98,23 @@ For advanced uses of Emacs, such as calling Emacs from a Makefile to automate do
 
 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=.
+Download the recompiled Emacs 26 ([[https://ftp.gnu.org/gnu/emacs/windows/emacs-26/emacs-26.1-i686.zip][for 32 bits architectures]]  or [[https://ftp.gnu.org/gnu/emacs/windows/emacs-26/emacs-26.1-x86_64.zip][for 64 bits architectures]] depending on your machine) and 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.
+
+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]]
 
-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.
+[[file:emacs_orgmode_images/scratch.png]]
+#+END_CENTER
 *** 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\=).
+=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.
 *** 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
@@ -206,7 +212,7 @@ tar tzf rr_org_archive.tgz
 
 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
+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
@@ -215,13 +221,14 @@ 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
+=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/ 
+# on Windows, use the file explorer to create the directory C:\Users\MyName\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
@@ -295,7 +302,7 @@ tar zcf replicable_article.tgz $FILE_LIST
 
 #+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.
+Download the following [[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.