diff --git a/module2/ressources/emacs_orgmode.html b/module2/ressources/emacs_orgmode.html index dcf0e4c496eb86d78a4a8e9514b13ecfc4c734d2..00633bbb939565368c6284af58155c0d16a3e36c 100644 --- a/module2/ressources/emacs_orgmode.html +++ b/module2/ressources/emacs_orgmode.html @@ -4,39 +4,46 @@

Table of Contents

@@ -57,13 +64,13 @@ the -

Installing emacs, org-mode, ess, and auctex.

-
+
+

Installing emacs, org-mode, ess, and auctex.

+
-
-

Linux (Debian, Ubuntu)

-
+
+

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 @@ -125,9 +132,13 @@ which is now deprecated.

-
-

Mac OS X

-
+
+

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: @@ -139,30 +150,48 @@ versions:

  • 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… +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 already use brew, simply do the following +Option 2: If you use Homebrew, do the following: 

    brew update
-brew install emacs [--with-cocoa]
+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
+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 +

    +
    +
    brew linkapps emacs
    -
    • +
    +

    +in order to make Emacs accessible directly from /Applications. +

    -
    -

    Windows

    -
    +
    +

    Windows

    +

    Install the .exe file from Vincent Goulet: https://vigou3.github.io/emacs-modified-windows/. It ships with recent @@ -174,11 +203,81 @@ versions:

  • ESS 17.11
    • +
    +

    Directory naming conventions

    +
    +

    +In all the following instructions, it is common to 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. +

    -
    -

    A simple "reproducible research" emacs configuration

    -
    +
    +

    Installing and configuring Matplotlib (graphic python library)

    +
    +

    +Open an DOS console and type the following command: +

    +
    +
    python -m pip install -U matplotlib
+
    +
    + +
    +

    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: +

    +
    +
    import matplotlib
+matplotlib.matplotlib_fname()
+
    +
    + +
    +

    matplotlib.png

    +
    + +

    +Open the matplotlibrc file and add a # at the beginning of the line +starting with backend, which amounts to use the default Agg value. +

    +
    +
    +
    +
    + +
    +

    A simple "reproducible research" emacs configuration

    +

    This section is illustrated in a video tutorial ("Mise en place Emacs/Orgmode" in French). Watching it before following the @@ -197,9 +296,9 @@ adding a few org-mode specific configurations.

    -
    -

    Step 0: Backup and download our configuration

    -
    +
    +

    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 @@ -220,9 +319,9 @@ rr_org/journal.org

    -
    -

    Step 1: Prepare your journal

    -
    +
    +

    Step 1: Prepare your journal

    +

    Create an org/ directory in the top of your home:

    @@ -239,9 +338,9 @@ should give a try.

    -
    -

    Step 2: Set up Emacs configuration

    -
    +
    +

    Step 2: Set up Emacs configuration

    +

    Copy rr_org/init.el in your ~/.emacs.d/ directory.

    @@ -253,16 +352,47 @@ configuration with the following command: emacs -q -l rr_org/init.el
    -
    -

    Step 3: Check whether the installation is working or not

    -
    +
    +

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

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

      3. +
    + +

    +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: 

     #+begin_src shell :session foo :results output :exports both
-ls -la
+ls -la # or dir under windows
 #+end_src
    @@ -286,22 +416,22 @@ is demonstrated in the -

    Step 4: Open and play with your journal:

    -
    +
    +

    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 -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. +backed up in a revision 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 replicable article

    -
    +
    +

    A stub of replicable article

    +

    This section is illustrated in a video tutorial ("Écrire un article réplicable avec Emacs/Orgmode" in French). Watching it before @@ -365,22 +495,22 @@ chunk of code when exporting.

    -
    -

    Emacs Tips and tricks

    -
    +
    +

    Emacs Tips and tricks

    +
    -
    -

    Cheat-sheets

    -
    +
    +

    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

    -
    +
    +

    Emacs

    +
    -
    -

    Org-mode

    -
    +
    +

    Org-mode

    +
    -
    -

    Video tutorials

    -
    +
    +

    Video tutorials

    +

    For those of you who prefer video explanations, here is a Youtube channel with many step by step emacs tutorials.

    -
    -

    Additional useful emacs packages

    -
    +
    +

    Additional useful emacs packages

    +
    -
    -

    Company-mode

    -
    +
    +

    Company-mode

    +

    Company-mode is a text completion framework for Emacs. It allows to have smart completion in emacs for the most common languages. If you @@ -424,9 +554,9 @@ official Web page: http://company-mode.

    -
    -

    Magit

    -
    +
    +

    Magit

    +

    Magit is an emacs interface for Git. Its usage is briefly illustrated in the context of this MOOC in a video tutorial ("Utilisation @@ -444,9 +574,9 @@ invoke magit by using C-x g.

    -
    -

    Other resources

    -
    +
    +

    Other resources

    +
    -
    -

    Additional Jupyter resources or tricks

    -
    +
    +

    Additional Jupyter resources or tricks

    +
    -
    -

    Tips and tricks

    -
    +
    +

    Tips and tricks

    +

    The following webpage lists several Jupyter tricks (in particular, it illustrates many Ipython magic commands) that should improve your @@ -41,9 +38,9 @@ now).

    -
    -

    Running R and Python in the same notebook

    -
    +
    +

    Running R and Python in the same notebook

    +

    The best solution to this is to install rpy2. On my machine, I have installed the python3-rpy2 debian package with apt-get install. E.g., @@ -91,9 +88,9 @@ plot(df)

    -
    -

    Exporting a notebook

    -
    +
    +

    Exporting a notebook

    +

    Obviously, you can convert to html or pdf using the using the File > Download as > HTML (or PDF) menu option. This can also be done from @@ -120,63 +117,43 @@ taste.

    -
    -

    Installing Jupyter on your own machine

    -
    +
    +

    Installing Jupyter on your own machine

    +
    -
    -

    Installing jupyter

    -
    +
    +

    Installing jupyter

    +

    -Here is what you should install: +Follow these instructions if you wish to have a similar Jupyter environment on you own machine.

    -
    -
    sudo apt-get install jupyter-notebook python3-pip python3-matplotlib python3-numpy
-
    -

    -On my machine, I got the version 5.4.1: +First, download and install Anaconda latest version. We use Anaconda version 4.5.4 on our server .
    +Anaconda includes Python, the Jupyter Notebook, and other commonly used packages for scientific computing and data science.

    -
    -
    jupyter-notebook --version
-
    -
    - -
    -5.4.1
-
-

    -The ipython notebook can then be run with the following command: +Then download the moocrr environment file and create it using conda:

    -
    jupyter-notebook
-
    -
    -
    -
    -
    -

    Using R

    -
    -

    -If you want to use the R kernel in jupyter, follow these instructions. -

    +
    conda env create -f environment.yml
 
-
    
-Alternatively, you can install rpy2 (see the Running R and Python in
-the same notebook section).
-
    
-
    
-
    sudo apt-get python3-rpy2
+# Windows activate the environment
+activate mooc_rr
+
+# Linux and MacOS activate the environment
+source activate mooc_rr
+
+jupyter notebook
    -
    -

    Exporting your notebooks with latex

    -
    + +
    +

    Exporting your notebooks with latex

    +

    Here is what I had to install on my recent debian machine to make sure the notebook export via latex works: @@ -188,23 +165,10 @@ sudo apt-get install texlive-xetex

    -
    -

    Interacting with GitLab

    -
    -

    -Here is our jupyter extension that allows to git push/pull from the -notebooks: -

    -
    -
    jupyter nbextension install https://raw.githubusercontent.com/brospars/nb-git/master/nb-git.js
-jupyter nbextension enable nb-git
-
    -
    -
    -
    -
    -

    Interesting extensions to improve notebook readability

    -
    + +
    +

    Interesting extensions to improve notebook readability

    +

    Here are two interesting extensions that can improve readability:

    @@ -231,14 +195,4 @@ jupyter-serverextension enable --py hide_code
    -
    -

    Installing JupyterHub   Benoit

    -
    -
    -

    -Benoit may give a few hints on this. -

    -
    -
    -