Les sources de ce document sont disponibles sur gitlab.
Version du 2019-03-31.

Quelques exemples de documents en Org-mode

Table of Contents

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. td2PS.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. 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. labbooksingle.org : ceci est un extrait du cahier de laboratoire tenu par 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. 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. labbookseveral.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. technicalreport.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 :