- [[#a-stub-of-replicable-article][A stub of replicable article]]
* Installing emacs, org-mode, ess, and auctex.
** OS-specific installation procedure
*** 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
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 [[file:rr_org/journal.org::*Org-mode][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 [[file:rr_org/journal.org::*Emacs%20shortcuts][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.
* 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
- [[file:org/journal.org::*Emacs%20shortcuts][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
- [[file:org/journal.org::*Org-mode][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 webpage: http://company-mode.github.io/
*** Magit
[[https://magit.vc/][Magit]] is an emacs interface for Git. It is very powerfull 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,
#+LaTeX:\footnote{Or figshare, or zenodo, or whatever platform you prefer!}.
We used the wonderful Org-mode
format\cite{schulte11:_activ_docum_org_mode} to both document our
experiments and create a replicable article that can be obtained on
[[https://github.com/alegrand/RR_webinars/blob/master/1_replicable_article_laboratory_notebook/replicable/article.org][Github]] as well. We could have used the Ipython
approach\cite{PER-GRA:2007} but we dishonestly ruled it out because
we wanted to be in full control of our C experimental setup and did
not know how to properly use it to write a replicable article.
Finally, it is important to explain that each measurement was
repeated five times and the set of experiments was absolutely not
randomized, which may compromise the validity of our observations
These informations were gathered and first demonstrated in my [[https://github.com/alegrand/RR_webinars/blob/master/1_replicable_article_laboratory_notebook/index.org][First
webinar on reproducible research: litterate programming]].
***** Emacs shortcuts
Here are a few convenient emacs shortcuts for those that have never
used emacs. In all of the emacs shortcuts, =C=Ctrl=, =M=Alt/Esc= and
=S=Shift=. Note that you may want to use two hours to follow the emacs
tutorial (=C-h t=). In the configuration file CUA keys have been
activated and allow you to use classical copy/paste (=C-c/C-v=)
shortcuts. This can be changed from the Options menu.
- =C-x C-c= exit
- =C-x C-s= save buffer
- =C-g= panic mode ;) type this whenever you want to exit an awful
series of shortcuts
- =C-Space= start selection marker although selection with shift and
arrows should work as well
- =C-l= reposition the screen
- =C-_= (or =C-z= if CUA keys have been activated)
- =C-s= search
- =M-%= replace
- =C-x C-h= get the list of emacs shortcuts
- =C-c C-h= get the list of emacs shortcuts considering the mode you are
currently using (e.g., C, Lisp, org, ...)
There are a bunch of cheatsheets also available out there (e.g.,
[[http://www.shortcutworld.com/en/linux/Emacs_23.2.1.html][this one for emacs]] and [[http://orgmode.org/orgcard.txt][this one for org-mode]] or this [[http://sachachua.com/blog/wp-content/uploads/2013/05/How-to-Learn-Emacs-v2-Large.png][graphical one]]).
***** Org-mode
Many emacs shortcuts start by =C-x=. Org-mode's shortcuts generaly
start with =C-c=.
- =Tab= fold/unfold
- =C-c c= capture (finish capturing with =C-c C-c=, this is explained on
the top of the buffer that just opened)
- =C-c C-c= do something useful here (tag, execute, ...)
- =C-c C-o= open link
- =C-c C-t= switch todo
- =C-c C-e= export
- =M-Enter= new item/section
- =C-c a= agenda (try the =L= option)
- =C-c C-a= attach files
- =C-c C-d= set a deadl1ine (use =S-arrows= to navigate in the dates)
- =A-arrows= move subtree (add shift for the whole subtree)
***** Org-mode Babel (for literate programming)
- =<s + tab= template for source bloc. You can easily adapt it to get
this:
#+BEGIN_EXAMPLE
#+begin_src shell
ls
#+end_src
#+END_EXAMPLE
Now if you =C-c C-c=, it will execute the block.
#+BEGIN_EXAMPLE
#+RESULTS:
| #journal.org# |
| journal.html |
| journal.org |
| journal.org~ |
#+END_EXAMPLE
- Source blocks have many options (formatting, arguments, names,
sessions,...), which is why I have my own shortcuts =<b + tab= bash
block (or =B= for sessions).
#+BEGIN_EXAMPLE
#+begin_src shell :results output :exports both
ls /tmp/*201*.pdf
#+end_src
#+RESULTS:
: /tmp/2015_02_bordeaux_otl_tutorial.pdf
: /tmp/2015-ASPLOS.pdf
: /tmp/2015-Europar-Threadmap.pdf
: /tmp/europar2016-1.pdf
: /tmp/europar2016.pdf
: /tmp/M2-PDES-planning-examens-janvier2016.pdf
#+END_EXAMPLE
- I have defined many such templates in my configuration. You can
give a try to =<r=, =<R=, =<RR=, =<g=, =<p=, =<P=, =<m= ...
- Some of these templates are not specific to babel: e.g., =<h=, =<l=,
- [[#rstudio-and-gitgithubgitlab][Rstudio and git/github/gitlab]]
- [[#cheat-sheets][Cheat Sheets]]
* Installing Rstudio
** 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/r-base][R 3.3.3-1]], [[https://packages.debian.org/stretch/r-cran-knitr][knitr 1.15.1]], and [[https://packages.debian.org/stretch/r-cran-ggplot2][ggplot 2.2.1]]
- Ubuntu (bionic 18.04) ships with [[https://packages.ubuntu.com/bionic/r-base][R 3.4.4]], and [[https://packages.ubuntu.com/bionic/r-cran-knitr][knitr 1.17]], and [[https://packages.ubuntu.com/bionic/r-cran-ggplot2][ggplot 2.2.1]]
- Ubuntu (artful 17.04) ships with [[https://packages.ubuntu.com/artful/r-base][R 3.4.2]], and [[https://packages.ubuntu.com/artful/r-cran-knitr][knitr 1.15]], and [[https://packages.ubuntu.com/artful/r-cran-ggplot2][ggplot 2.2.1]]
If your distribution is older than this, well, it may be a good time
for upgrading...
*** Installing R
Beforehand, you need to install the R language and convenient packages
Some instructions on installing R and knitr must be missing. This
should be tested and improved.
#+END_QUOTE
Download and install rstudio from the [[https://www.rstudio.com/products/rstudio/download/#download][Rstudio webpage]] by choosing the
right operating system.
Then open Rstudio and type the following commands in the console to
install knitr and ggplot2:
#+BEGIN_SRC R
install.packages("knitr")
install.packages("ggplot2")
#+END_SRC
* Installing Git
** 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).
Run (as root):
#+begin_src sh :results output :exports both
apt-get update ; apt-get install git
#+end_src
** Mac OSX and Windows
- Download and install Git from the [[https://git-scm.com/downloads][Git website]].
- Optional Git clients (should not be needed if you work within
Rstudio):
- [[https://www.sourcetreeapp.com/][SourceTree]]
- [[github desktop][GitHub Desktop]]
#+BEGIN_QUOTE
[[https://github.com/desktop/desktop/issues/852][Apparently]], this works with gitlab and https.
#+END_QUOTE
* Rstudio and git/github/gitlab
#+BEGIN_QUOTE
We may want to redo a screencast in French for this
#+END_QUOTE
- [[https://www.rstudio.com/resources/webinars/rstudio-essentials-webinar-series-managing-part-2/][This video on using git/githugb/gitlab from Rstudio]] (starting at time 9:09)
