#+TITLE: Quelques exemples de documents en Org-Mode
#+AUTHOR: Arnaud Legrand
#+AUTHOR: Arnaud Legrand
#+STARTUP: overview indent inlineimages logdrawer
#+STARTUP: overview indent inlineimages logdrawer
#+LANGUAGE: en
#+LANGUAGE: en
* Table of Contents :TOC:
* Table of Contents :TOC:
- [[#examples-from-the-video][Examples from the Video]]
- [[#les-documents-montrés-en-exemple-dans-les-vidéos-du-mooc][Les documents montrés en exemple dans les vidéos du MOOC]]
- [[#other-examples][Other examples]]
- [[#autres-exemples][Autres exemples]]
* Examples from the Video
* Les documents montrés en exemple dans les vidéos du MOOC
In the MOOC video, I quickly demo how org-mode can be used in various
Dans les vidéos, je montre rapidement comment org-mode peut être
contexts. Here are the (sometimes trimmed) corresponding
utilisé dans différents contextes (feuille de TD, journal, cahier de
org-files. These documents depend on many other external data files
laboratoire, article). Voici les fichiers org-mode (quelques fois un
and are not meant to lead to reproducible documents but it will give
peu épurés) correspondant. Ces documents dépendent souvent d'autres
you an idea of how it can be organized:
fichiers externes et ne sont pas prévu 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:journal.org][journal.org]]: an excerpt (I've only left a few code samples and links
1. [[file:journal.org][journal.org]]: ceci est un extrait (je n'ai laissé que quelques
to some resources on R, Stats, ...) from my own journal. This is a
exemples de programmes et de liens vers des ressources sur R, les
personal document where everything (meeting notes, hacking, random
statistiques, etc.) de mon propre journal. C'est un document
thoughts, ...) goes by default. Entries are created with the =C-c c=
personnel dans lequel tout ce que je peux faire (notes prises
shortcut.
pendant une réunion, petit code vite fait, idées diverses et
2. [[file:labbook_single.org][labbook_single.org]]: this is an excerpt from the laboratory notebook
variées, notes bibliographiques, ...) atterrit par défaut. Les
[[https://cornebize.net/][Tom Cornebize]] wrote during his Master thesis internship under my
entrées avec la date sont créées automatiquement à l'aide du
supervision. This a personal labbook. I consider this notebook to be
raccourci =C-c c=.
excellent and was the ideal level of details for us to communicate
2. [[file:labbook_single.org][labbook_single.org]]: ceci est un extrait du cahier de laboratoire
without any ambiguity and for him to move forward with confidence.
tenu par [[https://cornebize.net/][Tom Cornebize]] pendant son stage de Master sous ma
3. [[file:paper.org][paper.org]]: this is an ongoing paper based on the previous labbook of
direction. C'est un cahier de laboratoire personnel et que je
Tom Cornebize. As such it is not reproducible as there are hardcoded
considère comme excellent car il a le niveau de détail idéal pour
paths and uncleaned dependencies but writing it from the labbook was
nous permettre à la fois de communiquer sans aucune ambiguïté, pour
super easy as we just had to cut and paste the parts we
moi, de bien suivre ses avancées, et pour lui, d'avancer dans ses
needed. What may be interesting is the organization and the org
travaux avec confiance.
tricks to export to the right LaTeX style. As you may notice, in
3. [[file:paper.org][paper.org]]: ceci est un article en cours basé sur le cahier de
the end of the document, there is a commented section with emacs
laboratoire précédent. En l'état, il n'est pas reproductible car il
commands that are automatically executed when opening the file. It
y a plusieurs chemins absolus en dur et des dépendances logicielles
is an effective way to depend less on the =.emacs/init.el= which is
non explicitées mais sa rédaction à partir du cahier de laboratoire
generally customized by everyone.
a vraiment été très facile puisqu'il nous suffisait de
4. [[file:labbook_several.org][labbook_several.org]]: this is a labbook for a specific project shared
copier/coller et d'assembler toutes les parties dont nous avions
by several persons. As a consequence it starts with information
besoin de rendre compte. Ce qui peut être intéressant, c'est
about installation, common scripts, has section with notes about all
l'organisation de ce document (avec des sections cachées qui
our meetings, a section with information about experiments and an
récupèrent les données, les traitent et génèrent les figures) ainsi
other one about analysis. Entries could have been labeled by who
que la configuration org-mode permettant d'exporter avec le bon
wrote them but there were only a few of us and this information was
style LaTeX. Comme vous le remarquerez, il y a à la toute fin du
available in git so we did not bother. In such labbook, it is common
document une section avec des commandes emacs lisp commentées mais
to find annotations indicating that such experiment was =:FLAWED:= as
qui sont exécutées par emacs à l'ouverture du fichier. C'est une
it had some issues.
façon simple mais efficace de dépendre le moins possible du
5. [[file:technical_report.org][technical_report.org]]: this is a short technical document I wrote
=.emacs/init.el= que chacun personnalise à sa convenance.
after a colleague sent me a PDF describing an experiment he was
4. [[file:labbook_several.org][labbook_several.org]]: ceci est un petit exemple de cahier de
conducting and asked me about how reproducible I felt it was. It
laboratoire partagé par plusieurs personnes. Il commence donc par
turned out I had to cut and paste the C code from the PDF, then
des informations sur les dépendances logicielles à installer, les
remove all the line numbers and fix syntax, etc. Obviously I got
scripts les plus utiles. On y trouve ensuite une section avec des
quite different performance results but writing everything in
notes sur nos réunions puis une section avec des informations sur
org-mode made it very easy to generate both HTML and PDF and to
nos expériences et enfin une section sur les analyses de données.
explicitly explain how the measurements were done.
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.
5. [[file:technical_report.org][technical_report.org]]: ceci est un petit document technique que j'ai
écrit après qu'un collègue m'ai envoyé un document PDF décrivant
une expérience qu'il avait réalisé et souhaitait mon avis sur si
c'était suffisant d'un point de vue reproductibilité. Il s'est
avéré que 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
introduit 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.
* Other examples
* Autres exemples
Here are a few links to other kind of examples:
Voici à toute fin utile quelques liens vers d'autres types d'exemples:
- Slides: all my slides for a series of lectures is available here:
- John Kitchin est un expert org-modiste impliqué dans les questions
https://github.com/alegrand/SMPE. Here is a [[https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.org][typical source]] and the
de recherche reproductible et qui tient à jour un [[http://kitchingroup.cheme.cmu.edu/blog/][blog avec une
cours ainsi que pour des présentations sur la recherche
- his lecture on programming languages for undergrads:
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:
