# -*- coding: utf-8 -*-
# -*- mode: org -*-

#+TITLE:       Quelques exemples de documents en Org-mode
#+AUTHOR:      Arnaud Legrand
#+STARTUP: overview indent inlineimages logdrawer
#+LANGUAGE:    en


* Table of Contents                                                     :TOC:
- [[#les-documents-montrés-en-exemple-dans-les-vidéos-du-mooc][Les documents montrés en exemple dans les vidéos du MOOC]]
- [[#autres-exemples][Autres exemples]]

* Les documents montrés en exemple dans les vidéos du MOOC
Dans les vidéos, je montre rapidement comment Org-mode peut être
utilisé dans différents contextes (feuille de TD, journal, cahier de
laboratoire, article). Voici les fichiers Org-mode (quelques fois un
peu épurés) correspondants. Ces documents dépendent souvent d'autres
fichiers externes et ne sont pas prévus pour permettre de produire
directement des documents reproductibles mais ils peuvent vous donner
une idée de la façon dont ils peuvent être organisés :

1. [[file:td2_PS.ipynb][td2_PS.ipynb]] : ceci est une feuille de TD (en français) sur la
   génération de nombres aléatoires à destination d'étudiants de
   première année de Master en informatique. Elle utilise le langage
   R. Dans ce contexte d'enseignement, l'intérêt du notebook Jupyter
   est que les étudiants peuvent utiliser le Jupyterhub de l'université et n'ont
   donc rien à installer sur leur machine.
2. [[file:journal.org][journal.org]] : ceci est un extrait (je n'ai laissé que quelques
   exemples de programmes et de liens vers des ressources sur R, les
   statistiques, etc.) de mon propre journal. C'est un document
   personnel dans lequel tout ce que je peux faire (notes prises
   pendant une réunion, petit code vite fait, idées diverses et
   variées, notes bibliographiques...) atterrit par défaut. Les
   entrées avec la date sont créées automatiquement à l'aide du
   raccourci =C-c c=.
3. [[file:labbook_single.org][labbook_single.org]] : ceci est un extrait du cahier de laboratoire
   tenu par [[https://cornebize.net/][Tom Cornebize]] pendant son stage de Master sous ma
   direction. C'est un cahier de laboratoire personnel que je
   considère comme excellent car il a le niveau de détail idéal pour
   nous permettre à la fois de communiquer sans aucune ambiguïté, pour
   moi de bien suivre ses avancées, et pour lui d'avancer dans ses
   travaux avec confiance.
4. [[file:paper.org][paper.org]] : ceci est un article en cours basé sur le cahier de
   laboratoire précédent. En l'état, il n'est pas reproductible car il
   y a plusieurs chemins absolus en dur et des dépendances logicielles
   non explicitées mais sa rédaction à partir du cahier de laboratoire
   a vraiment été très facile puisqu'il nous suffisait de
   copier/coller et d'assembler toutes les parties dont nous avions
   besoin de rendre compte. Ce qui peut être intéressant, c'est
   l'organisation de ce document (avec des sections cachées qui
   récupèrent les données, les traitent et génèrent les figures) ainsi
   que la configuration Org-mode permettant d'exporter avec le bon
   style LaTeX. Comme vous le remarquerez, il y a à la toute fin du
   document une section avec des commandes Emacs Lisp commentées mais
   qui sont exécutées par Emacs à l'ouverture du fichier. C'est une
   façon simple mais efficace de dépendre le moins possible du
   =.emacs/init.el= que chacun personnalise à sa convenance.
5. [[file:labbook_several.org][labbook_several.org]] : ceci est un petit exemple de cahier de
   laboratoire partagé par plusieurs personnes. Il commence donc par
   des informations sur les dépendances logicielles à installer, les
   scripts les plus utiles. On y trouve ensuite une section avec des
   notes sur nos réunions puis une section avec des informations sur
   nos expériences et enfin une section sur les analyses de données.
   Idéalement, chaque entrée devrait être étiquetée par le nom de
   celui qui l'a écrite mais comme nous étions peu nombreux et que
   cette information est de toutes façons disponible dans le Git, nous
   ne nous sommes pas embêtés. C'est néanmoins une bonne habitude à
   prendre car si quelqu'un reformate le document (par exemple en
   ré-indentant et en changeant les espaces) il devient en général le
   dernier "propriétaire" de l'ensemble des lignes dans Git. Dans ce
   cahier de laboratoire, vous trouverez également des annotations
   indiquant que telle ou telle expérience est =:FLAWED:=. Ces
   annotations ont été réalisées a posteriori, lorsque l'on a réalisé
   qu'il y avait eu un problème et une petite explication (avec une
   nouvelle date) est en général alors ajoutée. L'annotation =:FLAWED:=
   nous permet de conserver l'ensemble des expériences tout en sachant
   d'un coup d'oeil lesquelles ne doivent pas être prises en compte.
6. [[file:technical_report.org][technical_report.org]] : ceci est un petit document technique que j'ai
   écrit après qu'un collègue m'a envoyé un document PDF décrivant
   une expérience qu'il avait réalisée alors qu'il souhaitait mon avis pour savoir si
   c'était suffisant d'un point de vue reproductibilité. Il s'est
   avéré que pour ré-exécuter le code présenté, j'ai pu copier-coller le
   code C à partir du PDF mais qu'il a fallu que j'enlève tous les
   numéros de lignes, que je corrige des problèmes de syntaxes
   introduits par la colorisation syntaxique et le formatage PDF,
   etc. Évidemment, les résultats de performance que j'ai obtenus
   étaient assez différents mais en écrivant tout en Org-mode, j'ai
   très facilement et très rapidement pu produire un document à la
   fois en HTML et en PDF tout en explicitant très précisément comment
   les mesures étaient effectuées.

* Autres exemples
Voici à toute fin utile quelques liens vers d'autres types d'exemples :
- John Kitchin est un expert org-modiste impliqué dans les questions
  de recherche reproductible et qui tient à jour un [[http://kitchingroup.cheme.cmu.edu/blog/][blog avec une
  foule d'astuces intéressantes]]. Vous trouverez ici un
  [[https://www.youtube.com/watch?v=IsSMs-4GlT8&list=FLQp2VLAOlvq142YN3JO3y8w&app=desktop][séminaire qu'il a donné à SciPy]].
- Présentations : l'ensemble des slides que j'utilise pour une série de
  cours ainsi que pour des présentations sur la recherche
  reproductible sont disponibles ici :
  [[https://github.com/alegrand/SMPE]]. Je n'ai pas fait d'effort
  particulier pour m'assurer que ça compile sur toutes les machines de
  la terre mais voici à quoi ressemblent typiquement les 
  [[https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.org][sources]] avec
  le [[https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.pdf][PDF résultant]].
- Lucas Schnorr, un collègue et ami, maintient :
  - un ensemble de modèles en Org-mode pour certaines conférences et
    journaux en informatique: [[https://github.com/schnorr/ieeeorg][IEEE]], [[https://github.com/schnorr/wileyorg][Wiley]], 
    [[https://github.com/schnorr/acmorg][ACM]], [[https://github.com/schnorr/llncsorg][LNCS]]
  - son cours de programmation (en portugais) pour les élèves de licence :
    https://github.com/schnorr/mlp/tree/master/conteudo


