Skip to content

M
mooc-rr-ressources
Commit fcc23c8c authored by Arnaud Legrand's avatar Arnaud Legrand
Browse files
Options

These automatically generated markdown files do not belong here anymore as we... 

These automatically generated markdown files do not belong here anymore as we use the gitlab pages mechanism.
parent 8986dad7
Hide whitespace changes
Inline Side-by-side
Showing with 0 additions and 8452 deletions
module1/ressources/Module1_1_MaterielSupplementaire_fr.md deleted 100644 → 0
View file @ 8986dad7
---
TITLE: Ressources pour la séquence 1 du module 1
AUTHOR: Christophe Pouzat
---\n
broken-links:nil c:nil creator:nil
Notes et références sur la séquence 1 : « Nous utilisons tous des cahiers de notes »
====================================================================================
Manuscrits annotés
------------------
En guise d'entrée dans l'univers des manuscrits annotés, je fais suivre
une petite sélection de passages du premier chapitre de « LA PAGE. DE
L'ANTIQUITÉ À L'ÈRE DU NUMÉRIQUE » d'Anthony Grafton (Hazan, 2012) :
``` example
Par le mouvement même de sa plume sur la page, il est clair que
Casaubon maîtrise tout ce qu'il lit. Constamment, il souligne des
mots et des expressions, il note en marge des mots clés et des résumés
montrant qu'il a lu attentivement, même quand, précise-t-il dans son
journal intime, il étudie en une journée quarante à cinquante pages
in-folio de grec émaillées de nombreuses abréviations. Les passages
plus importants donnent lieu en marge à des commentaires plus
longs. Sur les pages de titre, Casaubon porte très souvent — un peu
comme Montaigne — un jugement global sur la valeur de l'ouvrage.
Par ailleurs, il note ses réflexions dans des carnets, ou prend
des notes sur des textes qu'il ne peut pas acheter. Tels qu'ils sont
réunis dans sa bibliothèque, ses livres représentent une vie entière de
lecture que l'on peut reconstituer au fil des pages.
```
Pages 32 et 33, à propos d'[Isaac
Casaubon](https://fr.wikipedia.org/wiki/Isaac_Casaubon) (1559-1614).
``` example
Pourtant, Harvey a laissé beaucoup plus que cela, et notamment
des traces des ses lectures sous forme de plus d'une centaine de livres
couverts d'annotations magnifiquement écrites de sa belle écriture
italique — en plus des cahiers dans lesquels il notait des extraits.
Manifestement, Harvey considérait la lecture comme sa profession,
et il en a fait aussi un art. Décennie après décennie, il couche ses
pensées sur l'histoire dans une édition in-folio de 1555 de l'Histoire
romaine de Tite-Live. Ses notes, en latin pour la plupart, parcourent
les marges, se répandent entre les chapitres et remplissent
des feuilles volantes, prenant un aspect particulièrement érudit et
assez rébarbatif.
```
Pages 35 et 36, à propos de [Gabriel
Harvey](https://en.wikipedia.org/wiki/Gabriel_Harvey) (1545-1630).
``` example
... Mais dans l'exemplaire de travail qui subsiste du
texte, l'édition de base de 1549, il [Casaubon] introduit tant d'annotations
précises que les catalogueurs de la Bibliothèque bodléienne, qui n'étaient
pas rompus à la rhétorique, ont classé ce livre imprimé parmi les manuscrits.
```
Page 40.
Armoires à notes de Placcius et Leibniz
---------------------------------------
J'ai trouvé cet exemple dans les travaux d'[Ann
Blair](https://projects.iq.harvard.edu/ablair) comme « [The Rise of
Note-Taking in Early Modern
Europe](https://dash.harvard.edu/handle/1/4774908) » et son livre « [TOO
MUCH TO KNOW. Managing Scholarly Information before the Modern
Age](https://yalebooks.yale.edu/book/9780300165395/too-much-know) »,
publié chez *Yale University Press* en 2011.
La préface de « L'île des pingouins » d'Anatole France
------------------------------------------------------
Étant très loin de connaître Anatole France sur le bout des doigts, j'ai
trouvé la référence citée dans le remarquable article de Keith Thomas
publié par la *London Review of Books*, [le 10 juin
2010](https://www.lrb.co.uk/v32/n11/keith-thomas/diary). Cet article (en
anglais) décrit et discute le travail concret de prise de notes par un
historien, il est de plus très bien écrit et plein d'anecdotes.
Les livres de bord
------------------
Je remercie Joël Caselli de m'avoir aidé à interpréter le contenu du
livre de bord d'Éric Tabarly.
Le projet européen de reconstruction des climats des océans atlantique
et indien (et non pacifique comme je le dis dans le cours !) :
[*Climatological Database for the World's Oceans
1750-1850*](http://webs.ucm.es/info/cliwoc/) ; dispose d'un site
internet très intéressant (mais en anglais).
On trouvera des citations abondantes (et effrayantes) de livres de bord
de navires négriers dans le livre de Marcus Rediker « À bord du
négrier : Une histoire atlantique de la traite » (disponible en édition
de poche).
Un absent : le cahier de laboratoire classique
----------------------------------------------
Je traduis ici la section 6.2 *Notebooks and Records* du remarquable
livre de E. Bright Wilson *An Introduction to Scientific Research*
réimprimé par Dover.
Il est difficile de concevoir un cahier de laboratoire parfait et il est
malheureusement rare d'en trouver un qui soit même à peu près
satisfaisant ; la conservation d'une trace écrite du travail effectué
est néanmoins une source majeure d'efficacité. Il y aura forcément des
gens opposés à un ensemble de règles fixes, mais cela sera probablement
plus rare pour le rituel de garder un cahier que sur d'autres sujets.
Par conséquent, un ensemble de règles qui sont généralement considérées
comme satisfaisantes, voire même essentielles, seront quelque peu
dogmatiquement énoncées.
De grandes découvertes ont été retardées en raison d'une négligente
tenue des traces écrites. L'astronome Le Monnier est ainsi supposé avoir
observé la planète Uranus à plusieurs reprises – avant que son
identification comme planète ait été annoncée par Herschel –, mais a
décidé qu'elle était une étoile fixe. Cela s'explique probablement en
partie par le fait qu'il a écrit ses mesures sur des morceaux de papier,
y compris un sac en papier contenant à l'origine de la poudre pour
cheveux !
Les cahiers de laboratoire doivent être solidement reliés, d'une taille
approximative de 20 x 25 cm, avec des pages numérotées. Les feuilles
séparées sont trop facilement perdues pour être satisfaisantes, d'autant
plus qu'un cahier de laboratoire subit souvent un traitement un peu rude
avec peut-être des projections occasionnelles d'acide \[c'est un
physico-chimiste qui écrit\]. Le cas de mesures répétées constitue une
exception où une ébauche spéciale imprimée est souvent utile si un bon
système est établi pour collecter et relier les feuilles séparées. Les
pages avec des lignes sont généralement utilisées, mais il s'agit d'une
question de goût personnel, et certaines préfèrent des pages blanches ou
à carreaux. Un tampon en caoutchouc peut être utilisé pour fournir des
en-têtes pour les entrées les plus communes.
Les données doivent être entrées directement dans le cahier au moment de
l'observation. Il est intolérable d'utiliser sa mémoire ou des fragments
de papier pour l'enregistrement primaire, du fait de l'inévitabilité des
erreurs et des pertes. Il devrait donc y avoir une bonne place pour le
cahier à coté du poste de travail, et l'expérimentateur ne devrait
jamais être sans son cahier lorsqu'il est en action.
Les données doivent être enregistrées à l'encre, de préférence une encre
permanente, un buvard peut être pratique. Sinon, la trace écrite est
trop éphémère. Les cahiers sont soumis à une utilisation intensive et
les écritures au crayons se détériorent trop rapidement. Lorsque le
cahier peut être utilisé comme preuve pour un brevet, l'usage de l'encre
s'impose.
Des graphiques approximatifs et qualitatifs peuvent être dessinés
directement, mais les graphiques précis sont généralement préparés avec
le papier graphique du type le plus approprié \[pensez au papier
millimétré\]. Ils sont ensuite soigneusement collés dans le cahier, une
page vierge étant découpée afin de compenser l'épaisseur ajoutée.
Les cahiers doivent porter le nom de l'utilisateur et les dates
couvertes. \[…\]. Les huit ou dix premières pages devraient être
réservées pour une table des matières. Il s'agit de lignes ajoutées
chronologiquement pour chaque série d'expériences similaires, ainsi que
la référence de la page. La table des matières est extrêmement utile
pour trouver des éléments plus tard et est très simple à suivre. Un
index au dos du cahier est avantageux mais pas indispensable.
Chaque élément devrait être datée et, si plusieurs personnes utilisent
un cahier (généralement pas recommandé), paraphé. Le contenu ne devrait
pas inscrit de façon trop dense sur les pages ; le papier est bon marché
par rapport aux autres dépenses de recherche.
La principale difficulté est de décider ce qu'il faut écrire dans le
cahier. Évidemment, on entre les résultats numériques et les valeurs des
variables indépendantes telles que la température, la composition ou la
pression qui sont directement pertinentes. Il est également nécessaire
d'avoir un système d'entrées ou de références afin que, plus tard, il
soit possible de dire quel appareil a été utilisé et dans quelles
circonstances. Une description assez complète de l'appareil devrait être
conservée. Ensuite, lorsque des modifications sont apportées à
l'appareil, elles doivent être décrites immédiatement dans le cahier. Il
devrait également être possible de retracer la source des courbes
d'étalonnage, des corrections, etc., qui étaient appropriées aux données
d'un jour donné. Il est utile que les exigences relatives à l'écriture
d'un article, d'une thèse ou d'un livre soient gardées à l'esprit. Une
telle tâche, une fois effectuée, entraîne généralement la résolution
solennelle de garder un cahier plus détaillé dans le futur. Essayer de
comprendre le cahier de notes de quelqu'un d'autre constitue aussi un
exercice hautement salutaire. Toutes les références aux appareils, aux
lieux, aux horaires, aux livres, aux articles, aux graphiques et aux
personnes devraient être suffisamment explicites pour être
compréhensibles des années plus tard. **Il devrait être possible de
prendre chaque article scientifique et de montrer exactement où chaque
figure, description ou déclaration est justifiée par des observations
originales dans le cahier de laboratoire, et exactement pourquoi les
nombres final et original diffèrent, si tel est le cas**.
Un énoncé du but de chaque expérience et un résumé des conclusions
obtenues rendent le cahier beaucoup plus utile. Les croquis, dessins et
diagrammes sont essentiels. Comme tant d'observations sont visuelles,
*il est important de noter ce qui est réellement vu, y compris des
éléments qui ne sont pas entièrement compris lors de leur observation*.
Les expériences mauvaises ou non prometteuses, même celles considérées
comme des échecs, devraient être entièrement enregistrées. Elles
représentent un effort qui ne doit pas être gaspillé, car souvent
quelque chose peut être récupéré, même si ce n'est qu'une connaissance
de ce qu'il ne faut pas faire.
Les données doivent toujours être entrées dans leur forme la plus
primaire, et non après un calcul ou une transformation. Si c'est le
rapport de deux observations qui est intéressant, mais si les deux
nombres sont effectivement observés, les deux nombres doivent être
enregistrés. Si le poids précis d'un objet est important, les poids
d'équilibrage individuels utilisés et leur identification devraient être
inclus, c'est-à-dire le numéro de série de leur boîte. Dans le cas
contraire, il devient impossible d'appliquer ultérieurement des
corrections d'étalonnage ou de modifier les corrections si de nouvelles
valeurs apparaissent. Naturellement, ce détail n'est pas nécessaire si
seulement un poids approximatif est impliqué. La forme tabulaire est la
meilleure pour les données numériques. Les unités doivent être notées.
Lorsque des brevets sont impliquées, il peut être souhaitable
d'authentifier les pages des cahiers à intervalles réguliers. Le témoin
devrait être quelqu'un qui comprend le contenu mais qui n'est pas
impliqué dans la recherche. Un contenu ajouté ultérieurement à une page
devrait l'être dans une encre de couleur différente, et toutes les
modifications devraient être paraphées, authentifiées et datées si elles
sont susceptibles d'être importantes. Les entreprises industrielles font
ainsi généralement respecter leurs propres règles en matière de cahiers
de laboratoire.
**Numéros d'identification**. Il est stupide de consacrer du temps et de
l'argent à des enregistrements de différents types \[…\] si ceux-ci sont
ensuite perdus ou mélangés. Tout enregistrements qui ne peut être inclut
directement dans le cahier de notes devraient porter une identification
complète indélébile. Un système simple qui a fait ses preuves consiste à
écrire à l'encre sur chaque enregistrement un symbole identifiant le
cahier, puis le numéro de page sur lequel les données auxiliaires sont
enregistrées. Si plus d'un enregistrement sont mentionnés sur une page
du cahier, des lettres ou des chiffres supplémentaires peuvent être
ajoutés. Ainsi, EBW II 85c identifie le troisième enregistrement discuté
à la page 85 du deuxième cahier EBW. C'est mieux qu'un numéro de série
qui ne dit pas, sans clé supplémentaire, où chercher la description le
concernant dans le cahier. Un bon système de classement est
indispensable pour tous les films, les photographies, les schémas, les
graphiques, les diagrammes de circuit, les dessins, les plans, etc. Il
est plus difficile de concevoir des méthodes de dépôt satisfaisantes
pour des matériaux très petits ou très grands. Les premiers sont
facilement perdus et les dernier très volumineux. \[…\]
Il est important d'archiver les dessins et les plans à partir desquels
les appareils utilisés ont été construits, même si ces dessins sont
grossiers. Ils doivent être datés, paraphés et étiquetés ; en fait, tout
morceau de papier contenant une information utile devrait être marqué de
la sorte. Lorsqu'un équipement électronique ou autre est fabriqué, son
diagramme doit être soigneusement préparé et entièrement étiqueté avec
toutes les constantes. L'appareil doit porter un numéro de série qui
apparaît également sur ce diagramme. Lorsque des modifications sont
apportées, celles-ci doivent être indiquées sur le schéma et datées ou
un diagramme révisé et daté doit être préparé. L'ancien ne doit pas être
obscurci ou jeté, car il peut être nécessaire pour expliquer des données
antérieures, considérées ultérieurement comme étranges. \[…\]
Le but de toute cette pratique de prise de notes est de préserver la
valeur \[le temps et les moyens humains et matériels investis dans la
recherche\]. Elle devrait être soigneusement conçus pour s'adapter aux
conditions de chaque laboratoire et devraient être adéquate mais pas
trop élaborés. **Si l'on exige trop de la nature humaine, le système ne
fonctionnera pas**.
module1/ressources/Module1_1_SupplementaryMaterial.md deleted 100644 → 0
View file @ 8986dad7
---
TITLE: We all use notebooks (Module 1 sequence 1)
AUTHOR: Christophe Pouzat
---\n
broken-links:nil c:nil creator:nil
Introduction
============
This sequence discusses a much wider issue than *reproducible research*
(RR). Implementing RR requires thorough note-taking and note-taking
concerns everyone. The purpose of this sequence is therefore to remind
the reader / auditor that he/she already knows: **note-taking concerns
everyone**. Few examples are used to that end.
Annotated manuscripts
=====================
As an introduction to the world of annotated manuscripts, I quote now a
small selection of passages from the first chapter of *LA PAGE. DE
L'ANTIQUITÉ À L'ÈRE DU NUMÉRIQUE* (THE PAGE. FROM ANTIQUITY TO THE
DIGITAL ERA) by Anthony Grafton (Hazan, 2012):
``` example
By the very movement of his pen on the page, it is clear that
Casaubon masters everything he reads. He constantly underlines the importance of
words and expressions, he notes in the margin key words and summaries
showing that he has read carefully, even when, he states in his
diary that he studied in one day forty to fifty pages
in-folio of Greek with many abbreviations. The most important
passages give rise to longer comments in the margin.
On the title pages, Casaubon very often carries - a little
as Montaigne - a global judgment on the value of the work.
In addition, he notes his thoughts in notebooks, or takes
notes on texts he can't buy. As they are
gathered in his library, his books represent a whole life of
reading that can be reconstructed over the pages.
```
Pages 32 and 33, about [Isaac
Casaubon](https://en.wikipedia.org/wiki/Isaac_Casaubon) (1559-1614).
``` example
Yet Harvey left much more than that, including
traces of his readings in the form of more than a hundred books
covered with wonderfully written annotations of his beautiful slanted
writing - in addition to the notebooks in which he wrote extracts.
Clearly, Harvey considered reading to be his profession,
and he made it an art too. Decade after decade, he lays down his
thoughts on history in an in-folio edition of 1555 of Livy's "History
of Rome". His notes, mostly in Latin, go through
the margins, spread between chapters and fill in
loose sheets, taking on a particularly erudite aspect and
quite daunting.
```
Pages 35 and 36, on [Gabriel
Harvey](https://en.wikipedia.org/wiki/Gabriel_Harvey) (1545-1630).
``` example
... But in the remaining working copy of the
text, the basic edition of 1549, he [Casaubon] introduced so many annotations
that the cataloguers of the Bodleian Library, who were only
not familiar with rhetoric, have classified this printed book as a manuscript.
```
Page 40.
Note cabinets from Placcius and Leibniz
=======================================
I found this example in Ann Blair's work such as [The Rise of
Note-Taking in Early Modern
Europe](https://dash.harvard.edu/bitstream/handle/1/4774908/blair_notetaking.pdf?sequence=1)
and her book *TOO MUCH TO KNOW. Managing Scholarly Information before
the Modern Age*, published by Yale University Press in 2011.
On the preface to *Penguin Island*
==================================
The text can be found *legally* at several places, the [Project
Gutenberg](https://en.wikipedia.org/wiki/Project_Gutenberg) one is
missing the "Preface", so don't use it, go to one of the versions
available on [Internet
Archive](https://archive.org/search.php?query=title%3Apenguin%20island%20AND%20-contributor%3Agutenberg%20AND%20mediatype%3Atexts).
The importance of the preface in illustrated by the following two
quotations:
> One word more if you want your book to be well received, lose no
> opportunity for exalting the virtues on which society is based —
> attachment to wealth, pious senti- ments, and especially resignation
> on the part of the poor, which latter is the very foundation of order.
> Proclaim, sir, that the origins of property — nobility and police —
> are treat- ed in your history with the respect which these
> institutions deserve. Make it known that you admit the supernatural
> when it presents itself. On these conditions you will succeed in good
> society.
And more importantly for our present subject:
> The idea occurred to me, in the month of June last year, to go and
> consult on the origins and progress of Penguin art, the lamented M.
> Fulgence Tapir, the learned author of the ‘Universal Annals of
> Painting, Sculpture and Architecture’
>
> Having been shown into his study, I found seated before a roll-top
> desk, beneath a frightful mass of papers, an amaz- ingly short-sighted
> little man whose eyelids blinked behind his gold-mounted spectacles.
>
> To make up for the defect of his eyes his long and mobile nose,
> endowed with an exquisite sense of touch, explored the sensible world.
> By means of this organ Fulgence Tapir put himself in contact with art
> and beauty. It is observed that in France, as a general rule, musical
> critics are deaf and art critics are blind. This allows them the
> collectedness neces- sary for æsthetic ideas. Do you imagine that with
> eyes capable of perceiving the forms and colours with which mysterious
> nature envelops herself, Fulgence Tapir would have raised himself, on
> a mountain of printed and manuscript docu- ments, to the summit of
> doctrinal spiritualism, or that he would have conceived that mighty
> theory which makes the arts of all tunes and countries converge
> towards the Institute of France, their supreme end?
>
> The walls of the study, the floor, and even the ceiling were loaded
> with overflowing bundles, pasteboard boxes swollen beyond measure,
> boxes in which were compressed an in- numerable multitude of small
> cards covered with writing. I beheld in admiration minted with terror
> the cataracts of erudition that threatened to burst forth.
>
> ‘Master,’ said I in feeling tones, ‘I throw myself upon your kindness
> and your knowledge, both of which are inexhaustible. Would you consent
> to guide me in my arduous researches into the origins of Penguin art?’
>
> ‘Sir,’ answered the Master, ‘I possess all art, you under- stand me,
> all art, on cards classed alphabetically and in order of subjects. I
> consider it my duty to place at your dis- posal all that relates to
> the Penguins. Get on that ladder and take out that box you see above.
> You will find in it every- thing you require.’
>
> I tremblingly obeyed. But scarcely had I opened the fatal box than
> some blue cards escaped from it, and slipping through my fingers,
> began to rain down. Almost immediate- ly, acting in sympathy, the
> neighbouring boxes opened, and there flowed streams of pink, green,
> and white cards, and by degrees, from all the boxes, differently
> coloured cards were poured out murmuring like a waterfall on a
> mountain side in April. In a minute they covered the floor with a
> thick layer of paper. Issuing from their inexhaustible reservoirs with
> a roar that continually grew in force, each second in- creased the
> vehemence of their torrential fall. Swamped up to the knees in cards,
> Fulgence Tapir observed the cataclysm with attentive nose. He
> recognised its cause and grew pale with fright
>
> ‘What a mass of art !’ he exclaimed.
>
> I called to him and leaned forward to help him mount the ladder which
> bent under the shower. It was too late. Over- whelmed, desperate,
> pitiable, his velvet smoking-cap and his gold-mounted spectacles
> having fallen from him, he vainly opposed his short arms to the flood
> which had now mounted to his arm-pits. Suddenly a terrible spurt of
> cards arose and enveloped him in a gigantic whirlpool. During the
> space of a second I could see in the gulf the shining skull and little
> fat hands of the scholar, then it closed up and the deluge kept on
> pouring over what was silence and immobility. In dread lest I in my
> turn should be swallowed up ladder and all I maae my escape through
> the topmost pane of the window.
The logbooks
============
I would like to thank Joël Caselli for helping me interpret the content
of Éric Tabarly's logbook.
This example is only superficially anecdotal. Ten years ago, a European
project was aiming at estimating the Atlantic and Indian Oceans climates
during the 18th century using logbooks from ships of the West- and
East-India companies from the Kingdoms of Portugal, Spain, Holland,
Britain and France. See the [Climatological Database for the World's
Oceans 1750-1850](http://webs.ucm.es/info/cliwoc/).
In the same vein, logbooks from slave ships give a lot of quantitative
information about the slave trade between Africa and the "New World"
(see Marcus Rediker frightening book *The Slave Ship: A Human History*,
2007).
One missing: the classic laboratory notebook
============================================
I quote here Sec. 6.2 `Notebooks and Records` of the highly recommended
reading *An Introduction to Scientific Research* by E. Bright Wilson
(reprinted by Dover):
> It is hard to conceive of a perfect laboratory notebook, and it is
> regrettably rare to find one that is even moderately satisfactory; yet
> the keeping of good records of work done is a major key to efficiency.
> There are bound to be dissenters to any set of fixed rules, but these
> will probably be rarer for the ritual of notebook keeping than
> elsewhere. Consequently, a set of rules which is generally regarded as
> satisfactory, or even as essential, will be somewhat dogmatically
> stated.
>
> Some great discoveries have been delayed because of careless record
> keeping. Thus it is related that the astronomer Le Monnier observed
> the planet Uranus on several occasions, before its identification as a
> planet had been announced by Herschel, but decided that it was a fixed
> star. This was probably due in part to the fact that he wrote his
> measurements on scraps of paper, including a paper bag originally
> containing hair powder!
>
> Laboratory notebooks should be permanently and strongly bound and of
> sufficient size, say roughly 8 by 10 inches, with numbered pages.
> Loose-leaf pages or separate sheets are too easily lost to be
> satisfactory, especially since a laboratory notebook gets rather rough
> handling, and perhaps an occasional dousing with acid. An exception is
> the case of routine, repeated measurements, where a printed or
> mimeographed special blank is often useful if a good system is
> established for collecting and binding the separate sheets. Ruled
> pages are generally used, but this is a matter of personal taste, and
> some prefer unruled or cross-sectional pages. A rubber stamp may be
> used to provide headings for routine entries.
>
> Data should be entered directly into the notebook at the time of
> observation. It is intolerable to use memory or scraps of paper for
> primary recording, because of the inevitability of error and loss.
> Therefore, there should be a good place for the notebook at the
> operating position, and the experimenter should never be without his
> book when in action. Data should be recorded in ink, preferably a
> permanent brand, and a blotter should be handy. Otherwise the record
> is too ephemeral. Notebooks get hard usage, and pencil smudges
> rapidly. When the notebook may be used as evidence in a patent case,
> ink is much preferred.
>
> Rough, qualitative graphs can be drawn in directly, but more careful
> ones are usually best prepared on graph paper of the most appropriate
> type These are then carefully pasted in the notebook, a blank page
> being cut out in order to compensate for the bulk of the one added.
>
> Notebooks should carry the name of the user and the dates covered. It
> is convenient in a research group to agree on a standard size, but
> then some sort of external identification is a great timesaver. The
> first eight or ten pages should be reserved for a table of contents.
> This consists of a line added chronologically for each series of
> similar experiments, together with the page reference. The table of
> contents is enormously helpful in finding items later and is very
> simple to keep up. An index in the back of the book is advantageous
> but not indispensable.
>
> Each entry should be dated and, if several individuals use one book
> (not generally recommended), initialed. The material should not be
> crowded on the pages; paper is cheap compared with other research
> expenses. The principal difficulty is in deciding what to put in.
> Obviously, one enters numerical results and those values of the
> independent variables such as temperature, composition, or pressure
> which are directly concerned. It is also necessary to have a system of
> entries or references so that years later it will be possible to tell
> what apparatus was used and under what circumstances. Somewhere there
> should be available a rather complete description of the apparatus.
> Then, when modifications are made, they should be described
> immediately in the notebook. It should also be possible to trace back
> the source of calibration curves, corrections, etc., which were
> appropriate to the data of a given day. It is helpful if the
> requirements for writing a paper, a thesis, or a book are kept in
> mind. Such a task, once carried out, usually leads to solemn resolves
> to keep a more careful notebook in the future. Also extremely salutary
> is the effect of trying to figure out something from another’s book.
> All references to apparatus, places, times, books, papers, graphs, and
> people should be sufficiently explicit to be understandable years
> later. It should be possible to take each scientific paper and show
> just where every figure, description, or statement in it is backed up
> by original observations in the laboratory notebook, and exactly why
> the final and original numbers differ, if they do.
>
> Some statement of the purpose of each experiment and a summary of the
> conclusions reached make the notebook vastly more useful. Sketches,
> drawings, and diagrams are essential. Since so much observation is
> visual, it is important to record what is actually seen, including
> things not fully understood at the time. Bad or unpromising
> experiments, even those deemed failures, should be fully recorded.
> They represent an investment of effort which should not be thrown
> away, because often something can be salvaged, even if it is only a
> knowledge of what not to do. Data should always be entered in their
> most primary form, not after recalculation or transformation. If it is
> a ratio of two observations which is of interest but it is the two
> numbers which are actually observed, the two numbers should be
> recorded. If the precise weight of an object is important, the
> individual balance weights used and their identification should be
> included, i.e., the serial number of the box. Otherwise it is not
> possible to apply calibration corrections later or to change the
> corrections if new values appear. Naturally, this detail is not
> necessary if only a rough weight is involved. A tabular form is best
> for numerical data. Units should be noted.
>
> Where patent questions are involved, it may be desirable to witness
> and even to notarize notebook pages at intervals. The witness should
> be someone who understands the material but is not a coinventor.
> Material added to a page at a later date should be in a
> different-colored ink, and any alterations should be initialed,
> witnessed, and dated if they are likely to be important. Industrial
> concerns usually enforce their own rules concerning patent matters.
>
> Identification Numbers. It is foolish to spend time and money making
> records of various kinds such as pen-and-ink recorder sheets,
> photographic records, or spectra if these are then lost or mixed up.
> Every such record should carry indelibly on it complete
> identification. A simple system of doing this which has worked well in
> practice is to write in ink on each record a symbol identifying the
> notebook and then the page number on which the auxiliary data are
> recorded. If more than one record occurs on a page, letters or further
> numerals can be added. Thus EBW II 85c would identify the third record
> discussed on page 85 of the second EBW notebook. This is better than a
> serial number, which doesn’t tell without extra keying where to look
> for the notebook entry. A good filing system is indispensable for all
> films, photographs, charts, graphs, circuit diagrams, drawings,
> blueprints, etc. It is hardest to devise satisfactory filing methods
> for either very small or very large material. The former are easily
> lost and the latter very bulky. Small envelopes are useful for tiny
> films and also protect them from scratching.
>
> It is thoroughly worth while to save drawings and blueprints from
> which apparatus has been built, however rough these may be. These
> should be dated, initialed, and labeled; in fact every piece of paper
> containing useful material should be so marked. When an electronic or
> other similar piece of equipment is built, a careful circuit diagram
> should be prepared, fully labeled with all constants. The apparatus
> should carry a serial number which also appears on the diagram. When
> changes are made, these should be indicated on the diagram and dated
> or a revised, dated diagram made. The old one should not be obscured
> or thrown away because it may be required to explain earlier data,
> later found to be peculiar. It is convenient to draw such diagrams on
> tracing paper with a good black pencil. Cheap ozalid or similarly
> processed copies can then be made. One should be kept in the
> laboratory, where it will usually prove indispensable for trouble
> shooting. Sooner or later, however, it will be used as scratch paper
> by someone with a brilliant idea to demonstrate; so the official copy
> and spares should be filed elsewhere. A great deal of time is
> unnecessarily wasted poking around the insides of an apparatus trying
> to find out where some wire goes. \[…\] Labeling. Related to the
> question of notebooks and records is that of labeling. Naturally
> bottles of chemicals must carry adequate labels, which should include
> not only the chemical name but also the source, or a notebook page
> reference if there has been any special treatment, or initials and
> date. One research worker departed from a certain laboratory to take
> another job and left a good deal of material behind. One bottle of
> clear liquid carried no label. Those assigned to clean up examined it,
> smelled it, finally concluded that it was water, and poured it down
> the drain. It was water, all right—heavy water at $30 an ounce. Some
> supervisors relentlessly throw out unlabeled bottles on sight. It only
> needs to be done once or twice. Labels are also essential on all kinds
> of specimens, pieces of apparatus, gadgets, etc. Controls on apparatus
> should be labeled and the apparatus itself numbered. Every laboratory
> has orphaned pieces of equipment, often electronic, of which no one
> knows the nature and purpose. The notebook page system is good here,
> provided the old notebooks can be found. Labels should be attached so
> that they will stay. Metal tags can be riveted on. Paper labels should
> be covered with some sort of varnish.
>
> The whole purpose of all these recording systems is to preserve
> values. They should be carefully thought out to fit the conditions of
> each laboratory and should be adequate but not overelaborate. If too
> much is demanded of human nature, the system will break down.
module1/ressources/Module1_2_MaterielSupplementaire_fr.md deleted 100644 → 0
View file @ 8986dad7
---
TITLE: Ressources pour la séquence 2 du module 1
AUTHOR: Christophe Pouzat
---\n
broken-links:nil c:nil creator:nil
Notes et références sur la séquence 2 : « Un aperçu historique de la prise de notes »
=====================================================================================
Références générales
--------------------
En plus des deux livres déjà cités (en séquence 1) :
- « LA PAGE. DE L'ANTIQUITÉ À L'ÈRE DU NUMÉRIQUE » d'Anthony Grafton
(Hazan, 2012) ;
- « [TOO MUCH TO KNOW. Managing Scholarly Information before the
Modern
Age](https://yalebooks.yale.edu/book/9780300165395/too-much-know) »,
d'Ann Blair publié chez *Yale University Press* en 2011 ;
j'ai utilisé :
- « L'histoire du livre » de Frédéric Barbier ;
- le remarquable site de Jacques Poitou, [langages écritures
typographies](http://j.poitou.free.fr/pro/index.html) ;
- le site [l'aventure des écritures](http://classes.bnf.fr/ecritures/)
de la BNF ;
- le catalogue de l'exposition de la BNF « Tous les savoirs du monde :
Encyclopédies et bibliothèques de Sumer au XXIème siècle » ;
- « [Du papyrus à
l'hypertexte](http://litmedmod.ca/sites/default/files/pdf/vandendorpe-papyrusenligne_lr.pdf) »
de Christian Vandendorpe (La Découverte, 1999).
Sur les tablettes de cires
--------------------------
Voir le site de Jacques Poitou (d'où les illustrations sont empruntées)
et le livre de Frédéric Barbier, « L'histoire du livre ».
Sur le passage du rouleau (*volumen*) au codex
----------------------------------------------
Voir le livre de Frédéric Barbier, celui d'Anthony Grafton.
Le *volumen* est un livre à base de feuilles de papyrus collées les unes
aux autres et qui s'enroule sur lui-même. Il a été créé en Égypte vers
3000 av. J.-C. Le texte est rédigé en colonnes parallèles assez
étroites. C'est le support du texte par excellence durant les trente
siècles précédant notre ère, d'abord en Égypte, puis dans tout le monde
méditerranéen.
Comme l'explique Frédéric Barbier : « La forme du *volumen* impose une
pratique de lecture complexe : il faut dérouler (*explicare*) et
enrouler en même temps, ce qui interdit par exemple, de travailler
simultanément sur plusieurs rouleaux (un texte et son commentaire) ou de
prendre des notes, impose une lecture suivie et empêche la simple
consultation. »
Le *volumen* n'est clairement pas adapté à une lecture « nomade » ;
imagine-t-on Ulysse partant pour son Odyssée avec les 24 *volumen* de
l'Iliade ?
Le *volumen* est à l'origine du terme « volume » dans un « livre en
plusieurs volumes » comme dans la désignation du concept géométrique.
Le passage au codex repose sur deux innovations :
- la collection des tablettes de cires en « groupes reliés » ;
- la généralisation du parchemin (peau, généralement, de mouton
spécialement préparée) au détriment du papyrus. Cette généralisation
résulte une lutte pour l'hégémonie culturelle entre deux descendants
de généraux d'Alexandre le Grand, en effet d'après Pline l'ancien :
[Ptolémé
Épiphane](https://fr.wikipedia.org/wiki/Ptol%C3%A9m%C3%A9e_V)
d'Alexandrie cherchait à empêcher [Eumène
II](https://fr.wikipedia.org/wiki/Eum%C3%A8ne_II) d'établir une
bibliothèque à Pergame (au 2e siècle avant J.-C.) et avait interdit
l'exportation du papyrus (produit exclusivement en Égypte), ce qui
incita Eumène à chercher un substitut qui devint le parchemin.
Le remplacement du rouleau par le codex aura des conséquences majeures
sur l'organisation du livre ainsi que sur la façon de lire et il
permettra le développement ultérieur de l'imprimerie.
La principale révolution introduite par le codex est la notion de page.
Grâce à elle, le lecteur peut accéder de manière directe à un chapitre
ou à un passage du texte, alors que le rouleau impose une lecture
continue. **Les mots ne sont de plus pas séparés par des espaces**.
Comme l'écrit Collette Sirat : « Il faudra vingt siècles pour qu’on se
rende compte que l’importance primordiale du codex pour notre
civilisation a été de permettre la lecture sélective et non pas
continue, contribuant ainsi à l’élaboration de structures mentales où le
texte est dissocié de la parole et de son rythme. »
Au fil des siècles, le codex — qu'on désigne le plus souvent comme un
manuscrit — va évoluer et se donner peu à peu les attributs du livre
moderne : séparation entre les mots (VIIe siècle), début de ponctuation
(VIIIe siècle), table des matières, titre courant, marque de paragraphe
(XIe siècle), pagination, index (XIIIe siècle), etc.
Un point intéressant : le contenu de la Thora est « fixé » avant
l'apparition du codex et, aujourd'hui encore, la Thora est écrite sur
des *volumen* (dans les synagogues au moins). La religion chrétienne se
développe en même temps que le codex, adopte ce support et le répand ;
elle ne donnera jamais au *volumen* un statut « supérieur », pas plus
que ne le fera la religion musulmane.
Sur Eusèbe de Césarée
---------------------
Pour en savoir plus sur [Eusèbe de
Césarée](https://fr.wikipedia.org/wiki/Eus%C3%A8be_de_C%C3%A9sar%C3%A9e),
consultez le passionnant deuxième chapitre du livre d'Anthony Grafton.
Parallèle chinois
-----------------
Comme je le dis, mon inculture fait que je ne rends pas justice aux
contributions chinoises, musulmanes, précolombienne, etc. J'essaierai de
combler cette énorme lacune pour les seconde version du CLOM…
Ce que je dis sur le passage du volumen au codex accompagné d'un
développement des « outils de navigation » (index, table des matières,
etc) en Chine lors du développement de leishus vient du bouquin d'Ann
Blair (p. 31) qui cite un article de Susan Cherniack, « Book Culture and
Textual Transmission in Sung China », *Harvard Journal of Asiatic
Studies* Vol. 54, No. 1 (Jun., 1994), pp. 5-125.
Retour sur l'armoire à notes
----------------------------
Nous revenons sur le « bout de papier » ou la fiche comme support de
note. L'inconvénient est que le bout de papier ou la fiche se perdent
facilement et ne servent à rien s'ils ne sont pas **classés** en plus
d'être rangés. Problème résolu par l'armoire de Placcius. D'une certaine
façon, sa conception fait qu'on accède à son contenu par l'index.
L'avantage est que les notes peuvent être réorganisées si elles
contiennent des information sur plusieurs sujets. Elle peuvent aussi
être directement collées dans un livre lors de la composition d'un
florilège ou d'un ouvrage de synthèse.
Ce dernier procédé était très couramment employé par les humanistes et
les érudit de la renaissance et du début de la période moderne. [Conrad
Gessner](https://fr.wikipedia.org/wiki/Conrad_Gessner) (1516-1565) était
un champion de cette technique ; il obtenait même parfois ses fiches en
découpant les pages des livres. Encore une fois, ne faites pas cela avec
les livres de bibliothèques !
L'index et John Locke
---------------------
Sur l'origine de l'index, on pourra lire l'article de Jean Berger :
[Indexation, Memoire, pouvoir et representations au seuil du XIIe
siecle : La redecouverte des feuillets de tables du Liber De Honoribus,
premier cartulaire de la collegiale Saint-Julien de
Brioude](https://www.theindexer.org/files/25-2-berger.pdf), *The
Indexer*.
La méthode de John Lock est expliquée dans l'article *Indexing
commonplace books: John Locke’s method* d'Alan Walker, [The
Indexer](https://www.theindexer.org/issues/query.php?vol=22&iss=3), vol.
22, p. 114-118, 2001.
Sur [John Locke](https://fr.wikipedia.org/wiki/John_Locke) (1632-1704)
« papa du libéralisme » et actionnaire de la *Royal African Company*
principale compagnie négrière britannique, voir l'article
[Wikipedia](https://en.wikipedia.org/wiki/John_Locke#Constitution_of_Carolina)
(en anglais) et le livre « Contre-histoire du libéralisme » de Domenico
Losurdo (La Découverte / Poche, 2014, p. 34-36).
module1/ressources/Module1_2_SupplementaryMaterial.md deleted 100644 → 0
View file @ 8986dad7
---
TITLE: A historical survey of note taking
AUTHOR: Christophe Pouzat
---\n
broken-links:nil c:nil creator:nil
Illustrations used in the first figure
======================================
All illustrations are taken from Wikimedia Commons
- Top left: A clay tablet (pre-cuneiform period, -3000).
- Top center: A fresco from Pompeii with the portrait of [Terentius
Neo and his
wife](https://en.wikipedia.org/wiki/Portrait_of_Paquius_Proculo).
She carries a [wax tablet](https://en.wikipedia.org/wiki/Wax_tablet)
and a *stylus* (the main medium of note-takers up to the 19th
century); he carries a *volumen* or
[scroll](https://en.wikipedia.org/wiki/History_of_scrolls), the
stuff of books until the beginning of the Common Era.
- Top right: a notebook made of paper from the 17th century with
[commonplaces](https://en.wikipedia.org/wiki/Commonplace_book).
"Commonplace" is a translation of the Latin term locus communis
(from Greek tópos koinós, see literary topos) which means "a theme
or argument of general application", such as a statement of
proverbial wisdom (Wikipedia).
- Bottom left: An [index
card](https://en.wikipedia.org/wiki/Index_card), a notes medium
whose use exploded with bureaucratization and the development of
libraries. Still heavily used in the humanities. Apparently first
used (if not created) by the father of taxonomy, [Carl
Linneaus](https://en.wikipedia.org/wiki/Carl_Linnaeus). You can find
his cards at: <http://linnean-online.org/61332/#/0>.
- Bottom center: A [Post-it
note](https://en.wikipedia.org/wiki/Post-it_note) as most of us use
every day.
- Bottom right: A "modern days" numerical tablet.
Wax tablet and stylus
=====================
From the [Wikipedia page](https://en.wikipedia.org/wiki/Wax_tablet):
> A wax tablet is a tablet made of wood and covered with a layer of wax,
> often linked loosely to a cover tablet, as a "double-leaved" diptych.
> It was used as a reusable and portable writing surface in Antiquity
> and throughout the Middle Ages.
>
> Writing on the wax surface was performed with a pointed instrument, a
> stylus. Writing by engraving in wax required the application of much
> more pressure and traction than would be necessary with ink on
> parchment or papyrus,\[1\] and the scribe had to lift the stylus in
> order to change the direction of the stroke. Therefore, the stylus
> could not be applied with the same degree of dexterity as a pen. A
> straight-edged, spatula-like implement (often placed on the opposite
> end of the stylus tip) would be used in a razor-like fashion to serve
> as an eraser. The entire tablet could be erased for reuse by warming
> it to about 50 °C and smoothing the softened wax surface. The modern
> expression of "a clean slate" equates to the Latin expression "tabula
> rasa".
From the *scroll* to the *codex*
================================
The shift from the *scroll* to the *codex* is fundamental for
development of written civilization.
A scroll (from the Old French escroe or escroue), is a roll of papyrus,
[parchment](https://en.wikipedia.org/wiki/Parchment), or paper
containing writing.
From
[Wikipedia](https://en.wikipedia.org/wiki/History_of_scrolls#Replacement_by_the_Codex):
> The codex was a new format for reading the written word, consisting of
> individual pages loosely attached to each other at one side and bound
> with boards or cloth. It came to replace the scroll thanks to several
> problems that limited the scroll's function and readability. For one,
> scrolls were very long, sometimes as long as ten meters. This made
> them hard to hold open and read, a difficulty not helped by the fact
> that most scrolls in that era were read horizontally, instead of
> vertically as scrolling virtual documents are read now. The text on a
> scroll was continuous, without page breaks, which made indexing and
> bookmarking impossible. Conversely, the codex was easier to hold open,
> separate pages made it possible to index sections and mark a page, and
> the protective covers kept the fragile pages intact better than
> scrolls generally stayed. This last made it particularly attractive
> for important religious texts.
The bottom left mosaic shows Virgil seating (70-19 BCE) holding a scroll
of the *Aeneid*, with Clio, muse of history, also holding a scroll.
As explained by Frédéric Barbier (*Histoire du Livre*): "The scroll /
volumen imposes a complex reading practice: one must unroll
(*explicare*) and roll at the same time; that forbids working on several
scrolls (the original text and its commentary) at the same time or to
take notes. It imposes a continuous reading and making consultation
impossible."
Scrolls are clearly unsuited to "nomadic reading"; can you imagine
Ulysses embarking for his Odyssey carrying the 24 scrolls/volumen of the
Iliad?
The term *volumen* is the origin of our modern *volumes* (a book in
several volumes) as of the word for the geometrical concept.
Switching from scroll to codices required two innovations:
- The collection of wax tablets bound together with leather strands.
- The generalization of
[parchment](https://en.wikipedia.org/wiki/Parchment) (usually sheep
skin specially processed) as a replacement for
[papyrus](https://en.wikipedia.org/wiki/Papyrus). This
generalization could be due (according to Pliny the Elder) to a
rivalry between the cities of Pergamon and Alexandria for cultural
hegemony: [Ptolemy V
Epiphanes](https://en.wikipedia.org/wiki/Ptolemy_V_Epiphanes) King
of Egypt wanted to block [Eumenes
II](https://en.wikipedia.org/wiki/Eumenes_II) from developing in
Pergamon a library that could compete with the one of Alexandria; he
therefore imposed an embargo on papyrus export (Egypt was the sole
papyrus producer). Eumenes looked for an alternative and fostered
parchment development. The link between Pergamon and parchment is
much clearer in German where Pergamon is written in the way as in
English but where parchment is written *Pergament*.
Switching from scrolls to codices will have major consequences on books
organization as well as on the reading practices, it will later on allow
printing development.
The main revolution brought by the codex is the *page*. Thanks to this
structural element, the reader can access directly to a specific chapter
or a specific part of the text, while scrolls imposed continuous reading
**at a time when there were no blanks between words**. According to
Collette Sirat: "Twenty centuries will be necessary to realize the
paramount importance of the codex for our civilization through the
**selective reading** it made possible as opposed to the continuous
reading. It opened room for the elaboration of mental structures where
the text is dissociated from the speech and its rhythm."
Notice the red letters used on the codex (bottom right), an example of
[rubrication](https://en.wikipedia.org/wiki/Rubrication) used by scribes
to mark paragraphs. With printing and the high cost of colors it
entailed, an empty space started to be used to that end. Thinking about
it, colors don't cost anything on a numerical support and could
perfectly be used again in the same way.
Eusebius and the invention of cross-references
==============================================
From the Wikipedia page on
[Eusebius](https://en.wikipedia.org/wiki/Eusebius):
> Eusebius of Caesarea (ad 260/265 – 339/340), also known as Eusebius
> Pamphili, was a historian of Christianity, exegete, and Christian
> polemicist. He became the bishop of Caesarea Maritima about 314 AD.
> Together with Pamphilus, he was a scholar of the Biblical canon and is
> regarded as an extremely learned Christian of his time. He wrote
> Demonstrations of the Gospel, Preparations for the Gospel, and On
> Discrepancies between the Gospels, studies of the Biblical text.
According to Anthony Grafton and Megan Williams (2006) *Christianity and
the Transformation of the Book*, The Belknap Press of Harvard University
Press, his writings are crucial for our knowledge of the first three
centuries of Christian history. *He brought several essential
innovations to the book's organization like the cross-references*.
Eusebian canons
===============
Quote from
[Wikipedia](https://en.wikipedia.org/wiki/Eusebius#Biblical_text_criticism):
> For an easier survey of the material of the four Evangelists, Eusebius
> divided his edition of the New Testament into paragraphs and provided
> it with a synoptical table so that it might be easier to find the
> pericopes that belong together. These canon tables or "Eusebian
> canons" remained in use throughout the Middle Ages, and illuminated
> manuscript versions are important for the study of early medieval art,
> as they are the most elaborately decorated pages of many Gospel books.
*Codex* significance
====================
Following Frédéric Barbier (*HISTOIRE DU LIVRE*, Armand Colin, 2009):
- *Codex* invention is crucial for the development of written
civilization.
- The *codex* lends itself to **consultation reading**.
- We can add to the *codex* a "navigation system" making consultation
easier.
- We can take notes while consulting a *codex*.
- The combination of the *codex* with the *Carolingian minuscule*
constitutes an extremely powerful intellectual tools, never seen
before.
Example of *Carolingian minuscule* can be found on the corresponding
[Wikipedia page](https://en.wikipedia.org/wiki/Carolingian_minuscule).
Over centuries, *codices*—that we often call *manuscripts*—will slowly
evolve and gain modern days book attributes:
- separation between words (VIIth century),
- start of punctuation (VIIIth century),
- table of content,
- running title,
- paragraph marks (rubrication, XIth century),
- pagination,
- index (XIIIth century).
An interesting point: Torah's content got "fixed" before the *codex*
generalization and today Torah scrolls are still used.
Let us not forget China
=======================
The link between the *codex* generalization, on the one hand, and the
apparition of "navigation guides" like the table of content, the index,
the running title, on the other hand as a counterpart in the Chinese
civilization.
In China, competitive examinations to become a high ranking state
employee developed in the IXth century (CE). The main part of these exam
was a paper on what we would now call general knowledge of the Classics
where the students were asked to demonstrate their knowledge through
appropriate quotations.
To fulfill the need of "textbook" appropriate for this kind of
examination what is called
[leishus](https://en.wikipedia.org/wiki/Leishu) were produced. They are
described as follows on Wikipedia:
> The leishu are composed of sometimes lengthy citations from other
> works and often contain copies of entire works, not just excerpts. The
> works are classified by a systematic set of categories, which are
> further divided into subcategories. Leishu may be considered
> anthologies, but are encyclopedic in the sense that they may comprise
> the entire realm of knowledge at the time of compilation.
The efficient use of the leishu requires an indexing system, a table of
content, etc. Very interestingly, the scroll will be abandoned and the
codex will generalize in China around that time, as observed by Ann
Blair in her book *TOO MUCH TO KNOW*, Yale Univ. Press, 2010 (pp.
28-31).
Most of the leishus **were printed** (from the IXth century on!). The
picture on the right side (a banknote printing plate) is there to remind
us of who was (by far) the most advanced at that time. The Chinese were
of course printing their leishus on paper that they discovered in the
VIIIth century BCE.
Getting organized by using the right slot
=========================================
Now that we briefly reviewed the timeline of the main navigation
elements of the books—navigation elements that can of course be applied
to our lab/note-books—we come back to the paper slips and cards as notes
media.
We see (again) Placcius' and Leibniz's closet since it displays both the
benefits and the shortcomings of media that hold **a single note**.
Obvious shortcomings are:
- Paper slips and cards get easily lost.
- They are essentially useless if they are not **classified** in
addition to being filed.
These problems are solved by Placcius' cabinet, the content of which is
fundamentally accessed through the index.
Clear benefits are:
- Paper slips can be easily reorganized when they contain information
on several subjects.
- Paper slips can be directly pasted in a book when composing an
anthology or a compendium.
This last technique (pasting when making an anthology) was
systematically used by the Renaissance polymath [Conrad
Gessner](https://en.wikipedia.org/wiki/Conrad_Gessner) (1516-1565) who
even got his paper slips by cutting parts of pages from books (don't do
that with library books)!
Constructing a notebook index the John Locke way
================================================
We will now learn about an index construction technique due to [John
Locke](https://en.wikipedia.org/wiki/John_Locke) (1632-1704), the
grand-father of liberalism and a major investor in the *Royal African
Company*, the largest company in the
[slave-trade](https://en.wikipedia.org/wiki/John_Locke#Constitution_of_Carolina)
business at that time…
The indexing method is here illustrated using my own notebook. The two
pages that are displayed describe the structure of a dataset in the
[HDF5](https://www.hdfgroup.org/) format on the left side and the
corresponding structure (designed to map the former one) of a
`data frame` object of the [R](https://www.r-project.org/) language.
This dataset contain **calcium** concentration measurements made in
**neurons**. This notes were taken while writing some computer **code**
to analyze the data.
The precise content of the pages does not matter here in order to
understand how Locke's method works. The important points are:
- The pages are numbered (we are seeing here pages 86 and 87).
- Keywords are written at the bottom of the page: **code**; **neuro**;
**calcium**.
This method can be applied after note-taking, you just need to have few
pages left at the end of your notebook. That's in fact what I did since
I had started filling my notebook before learning about the method (I
learned about while preparing the French version of this lecture in
September 2017).
We now the index. It is located at the end of the notebook although
Locke recommends placing it at the beginning. Since I did not know about
the method when I started the notebook, I had to place it at the end…
The idea is to enter the keywords used in the notebook based on their
**first letter** and the **first vowel following the first letter**.
The index is therefore made of the 26 letters (you see letters "A" to
"R" here, the remaining ones are on the next page) subdivided the five
most common vowels ("y" goes together with "i" in that case).
Pages 86 and 87 contained the keyword **code** that goes into the entry
"Co" of the index (you see "86-89" because the following pages also
concern code for the same project). The keyword **Neuro** giving an
entry on line "Ne", while the keyword **Calcium** gives an entry on line
"Ca".
The keyword **Criquet** (not shown above) gives an entry on line "Ci".
It is also a good idea to list the set of keywords used in the notebook
on the page preceding or following the index.
module1/ressources/Module1_3_MaterielSupplementaire_fr.md deleted 100644 → 0
View file @ 8986dad7
---
TITLE: Ressources pour la séquence 3 du module 1
AUTHOR: Christophe Pouzat
---\n
broken-links:nil c:nil creator:nil
Notes et références sur la séquence 3 : « Du fichier texte au langage de balisage léger »
=========================================================================================
Fichier texte et éditeur de texte
---------------------------------
Une définition plus technique (et moins circulaire !) du fichier texte
se trouve sur [la page
wikipédia](https://fr.wikipedia.org/wiki/Fichier_texte) consacrée au
sujet. Pour plus de détails sur les éditeurs de texte, voir aussi la
[page wikipédia
correspondante](https://fr.wikipedia.org/wiki/%C3%89diteur_de_texte).
Un logiciel de « [traitement de
texte](https://fr.wikipedia.org/wiki/Traitement_de_texte) » est plus
sophistiqué qu'un simple éditeur de texte ; il permet de faire plus, ce
qui sous entend qu'il peut aussi ouvrir et manipuler des fichiers
textes.
\*Attention\* : le format « natif » des traitements de texte est
rarement un format texte. Les fichiers `doc` et `docx` de `Word` et
`odt` de `LibreOffice` *ne sont pas des fichiers textes*.
Le cas du fichier `PDF` ouvert avec un éditeur de texte
-------------------------------------------------------
Dans le cours filmé, j'utilise l'exemple du
[PDF](https://en.wikipedia.org/wiki/Portable_Document_Format) — je donne
l'adresse de la page wikipedia en anglais, bien plus complète que celle
en français — ouvert avec un éditeur de texte pour montrer que le
fichier ne peut pas être visualisé avec un tel logiciel, il faut un
logiciel de rendu dédié comme `Adobe Reader`, `Evince`, `MuPDF`,
`Aperçu`,… Vous remarquez néanmoins que le début du fichier contient du
texte (la première ligne nous apprend que le fichier utilise la version
1.3 du format `PDF`). Cette partie au format texte du fichier contient
les méta-données — qui ne sont pas montrées, en tout cas pas
directement, par les logiciels de rendu. Ces méta-données sont (en
partie) au format
[XMP](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform)
(*Extensible Metadata Platform*), nous y reviendrons dans la cinquème
séquence.
Sur l'UTF-8
-----------
Une table des symboles UTF-8, avec leur code se trouve à l'adresse :
<http://www.utf8-chartable.de/>. C'est pratique pour insérer un symbole
pas très courant comme la lettre « TLO » : Ꮰ de la langue cherokee, ou
le symbole mathématique ∀, « pour tout ».
Pour ceux qui doivent souvent utiliser des lettres grecs (par exemple
pour écrire des équations), il est possible sous Linux de (re)définir
des combinaisons de touches pour générer directement les dites lettres.
Ces combinaisons sont définies dans le fichier `.XCompose`, le début de
mon fichier contient :
``` example
# On charge la base de donnée de Compose la plus complète en UTF-8
include "/usr/share/X11/locale/en_US.UTF-8/Compose"
# espace insécable fine
<Multi_key> <Multi_key> <Space> : " " U202F
# Lettres greques
<Multi_key> <space> <a> : "α" Greek_alpha
<Multi_key> <space> <A> : "Α" Greek_ALPHA
<Multi_key> <space> <b> : "β" Greek_beta
<Multi_key> <space> <B> : "Β" Greek_BETA
<Multi_key> <space> <g> : "γ" Greek_gamma
<Multi_key> <space> <G> : "Γ" Greek_GAMMA
<Multi_key> <space> <d> : "δ" Greek_delta
<Multi_key> <space> <D> : "Δ" Greek_DELTA
<Multi_key> <space> <e> : "ε" Greek_epsilon
<Multi_key> <space> <E> : "Ε" Greek_EPSILON
<Multi_key> <space> <z> : "ζ" Greek_zeta
<Multi_key> <space> <Z> : "Ζ" Greek_ZETA
<Multi_key> <space> <h> : "η" Greek_eta
```
J'ai en plus redéfini la « \<Multi<sub>key</sub>\> » pour qu'elle
corresponde à la touche « impression d'écran » de mon clavier. Pour
apprendre à redéfinir des touches, consultez :
<https://wiki.archlinux.org/index.php/Keyboard_configuration_in_Xorg#Configuring_compose_key>.
module1/ressources/Module1_5_MaterielSupplementaire_fr.md deleted 100644 → 0
View file @ 8986dad7
---
TITLE: Ressources pour la séquence 5 du module 1
AUTHOR: Christophe Pouzat
---\n
broken-links:nil c:nil creator:nil
Notes et références sur la séquence 5 : « Les étiquettes et les logiciels d'indexation pour s'y retrouver »
===========================================================================================================
La structure de la séquence
---------------------------
Nous revenons ici sur le problème de l'indexation, pas tant sur
l'indexation d'un document unique que sur l'indexation de documents
multiples dans des formats divers :
- comme nous l'avons déjà affirmé, prendre des notes abondantes et
détaillées n'est utile que si nous pouvons retrouver les
informations qu'elles contiennent quand nous en avons besoin ;
- pour des notes contenues dans un seul fichier texte, la fonction de
recherche de notre éditeur favori nous permet généralement d'aller
assez loin ;
- pour des notes manuscrites contenues dans un cahier, la méthode de
Locke — que nous avons exposée dans notre deuxième séquence — et qui
repose sur des mots clé ou étiquettes, donne de bons résultats ;
- les notes manuscrites sur fiches sont généralement stockées dans un
meuble dont la structure matérialise un index — comme l'armoire de
Placcius et Leibniz — ;
- mais nous voulons ici aller plus loin, dans le cadre restreint des
« notes » numérisées, en discutant de l'indexation de fichiers
multiples qu'ils soient au format « texte » où dans d'autres format
comme les images `jpg` où les fichier `pdf` ;
- cela nous amménera à introduire les « moteurs de recherche de
bureau » et à expliquer comment des `étiquettes` ou `mots-clés`
peuvent être ajoutés à nos fichiers.
La citation de Leibniz
----------------------
J'ai trouvé la citation introductive :
« Il me semble que l'apparat savant contemporain est comparable à un
grand magasin qui contient une grande quantité de produits, stockés de
façon totalement désordonnée, mélangée ; où les nombres ou lettres
d'indexation manquent ; où les inventaires et livres de comptes pouvant
aider à ordonner le contenu ont disparus.
Plus grande est la quantité d'objets amassés, plus petite est leur
utilité. Ainsi, ne devrions nous pas seulement essayer de rassembler de
nouveaux objets de toutes provenances, mais nous devrions aussi essayer
d'ordonner ceux que nous avons déjà. »
sur le site <http://www.backwordsindexing.com/index.html>, c'est donc
une traduction de traduction. J'emploie ici le terme volontairement
anachronique d'« \[apparat
savant\](<https://fr.wikipedia.org/wiki/Apparat_savant>) » qui est un
terme technique de l'édition désignant : citations, références et
sources, notes en bas de pages, introduction, texte en langue originale
(en parallèle avec la traduction), commentaire historique ou
philologique, index fontium (les sources), index locorum (références
avec renvoi à la page où le passage est cité ou mentionné, par ex. :
Évangile selon Marc 1, 1 : p. 100), index nominum (les noms propres),
index rerum (les thèmes), etc. La référence au « grand magasin » est,
elle aussi anachronique !
Leibniz a, pendant une bonne partie de sa vie, « gagné celle-ci » comme
[bibliothécaire](https://www.reseau-canope.fr/savoirscdi/societe-de-linformation/le-monde-du-livre-et-des-medias/histoire-du-livre-et-de-la-documentation/biographies/leibniz-le-bibliothecaire.html),
ce qui explique en partie sont intérêt très poussé pour les questions de
classifications, d'indexations, etc.
Rechercher avec un éditeur de texte
-----------------------------------
La diapo correspondante rappelle juste au lecteur quelque chose qu'il
sait déjà et qui est vue, par les gens qui passent des notes « papier »
aux notes « numériques », comme le gros attrait du numérique.
Les gens de monde Unix/Linux connaissent aussi généralement le programme
[grep](https://fr.wikipedia.org/wiki/Grep) qui permet de faire des
recherches de mots et, plus généralement d'[expressions
régulières](https://fr.wikipedia.org/wiki/Expression_r%C3%A9guli%C3%A8re),
sur un ou *plusieurs* fichiers ; nous y reviendrons.
Recherche avec index construit « à la main » sur des cahiers de notes
---------------------------------------------------------------------
Là encore, il s'agit juste d'un rappel pour les lecteurs assidus de ce
cours ; à ce stade se sont des experts dans la méthode d'indexation de
Locke.
Recherche avec index « matérialisés »
-------------------------------------
Encore un rappel pour les lecteurs.
Vers les outils « sophistiqués » de l'informatique
--------------------------------------------------
- les techniques que nous venons de voir ou revoir ne fonctionnent que
pour un seul « document » — recherche avec l'éditeur de texte, index
d'un cahier — et/ou pour un seul type de document ;
- les outils informatiques dont nous disposons nous permettent d'aller
plus loin dans l'indexation des fichiers numériques ;
- il est possible de rajouter des étiquettes ou mots-clés à des
fichiers textes comme à des fichiers images (\`jpg\`, \`png\`) ou
des fichiers « mixtes » (\`pdf\`) grâce aux métadonnées qu'ils
contiennent ;
- les moteurs de recherche de bureau permettent d'indexer l'ensemble
des fichiers textes d'une arborescence donnée mais aussi les
métadonnées des autres fichiers.
Les moteurs de recherche de bureau
----------------------------------
Les moteurs de recherche de bureau comme :
- [DocFetcher](http://docfetcher.sourceforge.net/fr/index.html)
(Linux, MacOS, Windows) ;
- [Tracker](https://wiki.gnome.org/Projects/Tracker) (Linux) ;
- [Recoll](https://www.lesbonscomptes.com/recoll/index.html.fr)
(Linux, MacOS, Windows) ;
- [Spotlight](https://fr.wikipedia.org/wiki/Spotlight_(moteur_de_recherche))
(MacOS) ;
permettent de rechercher le *contenu* des fichiers textes, des
courriels, des fichiers générés par les `traitements de texte`
— c'est-à-dire des fichiers qui contiennent essentiellement du texte,
mais qui sont stockés dans un format type `doc`, `docx`, `odt`, etc qui
ne sont pas des formats texte —, des fichiers `pdf` — quand ceux-ci ne
sont pas des *images* de textes —, mais aussi des
[métadonnées](https://en.wikipedia.org/wiki/Portable_Document_Format#Metadata)
des fichiers `pdf`, etc.
Les moteurs de recherche de bureau « utilisent des techniques
d'[indexation](https://fr.wikipedia.org/wiki/Indexation_automatique_de_documents)
qui permettent de réduire considérablement les temps de recherche, par
rapport aux fonctions de recherche intégrées par défaut aux systèmes
d'exploitation. Au contraire de ces derniers, ils prennent aussi souvent
en charge les
[métadonnées](https://fr.wikipedia.org/wiki/M%C3%A9tadonn%C3%A9e), et
sont capables de faire une [analyse
syntaxique](https://fr.wikipedia.org/wiki/Analyse_syntaxique) des
fichiers. » (Source : [Moteur de recherche de
bureau](https://fr.wikipedia.org/wiki/Moteur_de_recherche_de_bureau) sur
Wikipédia)
Comme exemple de « fonctions de recherche intégrées par défaut », on
trouvera sur les systèmes Unix/Linux le programme [grep
](https://fr.wikipedia.org/wiki/Grep)avec lequel nous pouvons chercher
les occurrences du mot « Galilée » dans le répertoire
« RR<sub>MOOC</sub> » de notre cours sur GitHub (après l'avoir cloné) :
``` bash
grep -r Galilée
```
``` example
PITCHME.md:## Galilée qui observe les lunes de Jupiter
PITCHME.md:Le 7 janvier 1610, Galilée fait une découverte capitale : il remarque trois « petites étoiles » à côté de Jupiter. Après quelques nuits d'observation, il découvre qu'il y en a une quatrième et qu'**elles accompagnent la planète**, c'est ce qu'il note sur son cahier d'observations. Ce sont les satellites visibles de Jupiter, qu'il nommera plus tard les étoiles Médicées ou astres médicéens – en l'honneur de ses protecteurs, la Famille des Médicis – et qui sont aujourd'hui appelés lunes galiléennes.
PITCHME.md:Ces observations amèneront Galilée à rejeter l'hypothèse géocentrique (la terre est le centre de l'Univers et tout tourne autour d'elle) en faveur du système copernicien héliocentrique. Cela l'amènera indirectement (je « fais court ») et bien plus tard, le 22 juin 1633, a être condamné par l'inquisition, ce qui lui vaudra de finir ses jours en résidence surveillée.
PITCHME.md:Remarquez l'avantage des « bouts de papiers classés » de Placcius et Leibniz sur le _codex_ de Galilée : les premiers peuvent être facilement réordonnées.
Notes_module1.org:- [[https://en.wikipedia.org/wiki/Galileo_Galilei][la page wikipedia sur Galilée]] contient de nombreux liens, certains vers ses cahiers de notes ;
Notes_module1.org:Comme exemple de « fonctions de recherche intégrées par défaut » on trouvera sur les systèmes Unix/Linux le programme [[https://fr.wikipedia.org/wiki/Grep][grep ]]avec lequel nous pouvons chercher les occurrences du mot « Galilée » dans le répertoire « RR_MOOC » de notre cours sur GitHub (après l'avoir cloné) :
Notes_module1.org:grep -r Galilée
```
Une version plus sophistiquée de `grep` est fournie par le programme
[cgvg](http://uzix.org/cgvg.html).
Pourquoi des étiquettes
-----------------------
Une requête basée sur un simple mot renvoie souvent un très grand nombre
de propositions, même si la plupart des moteurs de recherche de bureau
permettent de filtrer ces dernières. Une façon efficace de limiter leur
nombre est d'inclure dans nos documents des étiquettes, c'est-à-dire des
points d'ancrage labelisés, qui seront aisément indexés par le moteur de
recherche de bureau et dont le label ne correspond à aucun mot ou
locution du dictionnaire — nous effectuons ainsi une version simplifiée
du travail de l'*indexeur*, la personne chargée de construire l'index
d'un livre. Pour que l'étiquette garde un sens, il suffit d'encadrer un
mot par une paire de signes de ponctuation comme « : », « ; » ou « ? ».
Un label comme « :code: » sera facilement mémorisé et fera un parfait
équivalent du mot-clé « code » utilisé dans l'exemple du cahier de note
de la deuxième séquence de ce module — pour illustrer la méthode de
Locke.
Il nous reste encore nous reste encore un détail technique à régler dans
le cas de nos notes prises en format texte comme `Markdown`. En effet,
nous ne souhaitons pas que nos étiquettes apparaissent dans les sorties
`html`, `pdf` ou `docx` de nos notes. Un façon de procéder, pour les
langages de balisage légers qui ne disposent pas d'étiquettes — par
exemple, `Markdown` n'en dispose pas, alors que `org` en a — et de les
inclure dans des commentaires. En `Markdown`, tout ce qui est encadré
par `<!--` et `-->` est considéré comme un commentaire et ne figure pas
dans les sorties `html` ou `pdf` des notes. Nous pouvons ainsi
utiliser :
``` example
<!-- ;code; -->
```
à l'endroit de nos notes où nous souhaitons aller rapidement lorsque que
nous cherchons une information relative à de la programmation
(production de codes).
Les métadonnées
---------------
### Fichiers images
Nous savons à présent comment rajouter des étiquettes à un fichier au
format texte, mais nous devons souvent aussi travailler avec des
fichiers contenant des images ou des photos, comme les fichiers
[JPEG](https://fr.wikipedia.org/wiki/JPEG) — les appareils photos
numériques utilisent tous ce format —,
[GIF](https://fr.wikipedia.org/wiki/Graphics_Interchange_Format) ou
[PNG](https://fr.wikipedia.org/wiki/Portable_Network_Graphics). La
question se pose alors, peut-on ajouter des étiquettes à nos fichiers
images de sorte que nos moteurs de recherche de bureau les indexent ? La
réponse et oui, grâce aux
[métadonnées](https://fr.wikipedia.org/wiki/M%C3%A9tadonn%C3%A9e) que
contiennent ces fichiers. Les métadonnées, dans ce cas, sont des données
stockées dans le fichier mais qui ne sont pas montrées par le logiciel
de rendu (en tout cas, pas montrées par défaut). Nous savons tous que
ces métadonnées « existent » ; ce sont elles qui contiennent la date, la
localisation GPS, le temps d'exposition, etc. de nos photos numériques.
Dans les fichiers `JPEG`, elles sont stockées suivant l'[exchangeable
image file
format](https://fr.wikipedia.org/wiki/Exchangeable_image_file_format)
(`EXIF`). La plupart des logiciels de manipulations d'images et de
photos permettent d'accéder au contenu des métadonnées et de les
modifier. L'exemple illustré dans le cours utilise une solution très
simple en « ligne de commande »,
[ExifTool](http://owl.phy.queensu.ca/~phil/exiftool/) qui permet de
visualiser et de modifier les métadonnées. D'autres logiciels comme
[exiv2](http://www.exiv2.org/index.html) ou
[ImageMagick](https://imagemagick.org/script/index.php) permettent de le
faire (pour ne citer que des logiciels libres disponibles sur Linux,
Windows et MacOS). Certains des éléments du format `EXIF` sont des
chaînes de caractères, c'est-à-dire du texte, que nous somme libres
d'utiliser comme nous le souhaitons ; nous pouvons dès lors les utiliser
pour rajouter nos étiquettes. Nous illustrons dans le cours comment le
faire avec `ExifTool`, mais nous aurions aussi pu le faire avec le
programme
[mogrify](https://www.imagemagick.org/script/command-line-options.php#comment)
d'ImageMagick. Tous les moteurs de recherche de bureau que nous avons
mentionné vont « aller regarder » les métadonnées des fichier `JPEG`
lors de la phase d'indexation et nous permettront ainsi d'exploiter les
étiquettes que nous y aurons insérées.
`EXIF` n'est pas le seul format de métadonnées existant ; un format plus
récent est l'[Extensible Metadata Platform
](https://fr.wikipedia.org/wiki/Extensible_Metadata_Platform)(`XMP`),
disponible pour un plus grand nombre de formats de fichiers — il n'est
pour l'instant pas lu sur les fichiers `JPEG` par `DocFetcher`, c'est
pourquoi nous avons mis en avant le format `EXIF`, mais cela devrait
évoluer assez vite ; les autres moteurs comme `Tracker` et `Recoll` le
lisent.
### Fichiers `PDF`
En plus des fichiers images, nous sommes tous très fréquemment amenés à
travailler avec les fichiers « composites » — contenant textes, images,
et plus — que sont les fichiers
[PDF](https://fr.wikipedia.org/wiki/Portable_Document_Format). Ces
fichiers contiennent eux aussi des métadonnées ; c'est d'ailleurs pour
eux qu'Adobe a initialement introduit le format `XMP` que nous venons de
discuter. Ces métadonnées peuvent être lues et modifiées, en particulier
l'élément `Keywords` (mot-clé) qui peut contenir des chaînes de
caractères de longueur arbitraires et qui est parfait pour accueillir
nos étiquettes. Le programme `ExifTool`, permet de modifier les
métadonnées des fichiers `PDF`. Les moteurs de recherche de bureau que
nous avons mentionnés, vont tous aller lire les métadonnées des fichiers
`PDF` lors de la phase d'indexation.
### Fichiers audios
Les formats audio comme le
[mp3](https://fr.wikipedia.org/wiki/MPEG-1/2_Audio_Layer_III) ou le
[ogg](https://fr.wikipedia.org/wiki/Ogg) contiennent eux aussi des
métadonnées, où sont stockés les titres, noms des interprètes, etc ; ces
métadonnées peuvent être modifiées et sont lues par les moteurs de
recherche de bureau lors de la phase d'indexation.
module1/ressources/introduction_to_markdown.md deleted 100644 → 0
View file @ 8986dad7
---
title: Introduction to Markdown
date: Wed Mar 20 13:57:10 2019
---
This document presents a brief overview of the Markdown syntax and
builds on a [presentation from the Github
team](https://guides.github.com/features/mastering-markdown/) and [blog
post from Archer
Reilly](http://csrgxtu.github.io/2015/03/20/Writing-Mathematic-Fomulars-in-Markdown/).
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Syntax](#syntax)
- [Headers](#headers)
- [Emphasis](#emphasis)
- [Lists](#lists)
- [Images](#images)
- [Links](#links)
- [Blockquotes](#blockquotes)
- [Inline code](#inline-code)
- [Writing Math](#writing-math)
- [Greek Letters](#greek-letters)
- [Usual functions and operators](#usual-functions-and-operators)
- [Exponents and indices](#exponents-and-indices)
- [Fractions, binomial coefficients, square roots,
…](#fractions-binomial-coefficients-square-roots-)
- [Summations and integrals](#summations-and-integrals)
- [Outfits ☺](#outfits-smiley)
- [About `markdown`](#about-markdown)
# Syntax
## Headers
``` example
# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag
```
## Emphasis
``` example
*This text will be italic*
_This will also be italic_
**This text will be bold**
__This will also be bold__
_You **can** combine them_
```
## Lists
### Unordered
``` example
- Item 1
- Item 2
- Item 2a
- Item 2b
```
### Ordered
``` example
1. Item 1
2. Item 2
3. Item 3
1. Item 3a
2. Item 3b
```
## Images
``` example
![GitHub Logo](/images/logo.png)
Format: ![Alt Text](url)
```
## Links
``` example
http://github.com - automatic!
[GitHub](http://github.com)
```
## Blockquotes
``` example
As Kanye West said:
> We're living the future so
> the present is our past.
```
## Inline code
```` example
To print some text with python, you should use the `print()` function.
```
print("Hello world!")
```
````
# Writing Math
Math formulas are easy to write using Markdown, either using the
**inline** mode or the **displayed formulas** mode. With the inline
mode, formulas are inlined in the current paragraph whereas with the
displayed mode, they appear as centered and emphasized.
The formatting generally slightly differs in both cases since, to
display nicely on a single line, it is generally required to pack them a
bit more than when they are emphasized.
To write formulas using the **inline** mode, they should be surrounded
by a single `$` (as a consequence, whenever you need to use the original
dollar symbol, you should prefix it with a backslash: `\$`). To write
formulas using the **displayed** mode, they should be surrounded by a
`$$`. Here are a few examples:
``` example
This expression $\sum_{i=1}^n X_i$ is inlined.
```
This expression \(\sum_{i=1}^n X_i\) is inlined.
``` example
This expression is emphasized:
$$\sum_{i=1}^n X_i$$
```
This expression is emphasized:
\[\sum_{i=1}^n X_i\]
In the rest of this section we present a brief selection of common
symbols and commands. Actually, almost any classical LaTeX command can
used as such in Markdown, provided it is surrounded by a `$`. For more
complete examples, please have a look at these ces [examples by James H.
Steiger](http://www.statpower.net/Content/310/R%2520Stuff/SampleMarkdown.html).
## Greek Letters
| Symbol | Command |
| ---------- | ---------- |
| \(\alpha\) | `$\alpha$` |
| \(\beta\) | `$\beta$` |
| \(\gamma\) | `$\gamma$` |
| \(\Gamma\) | `$\Gamma$` |
| \(\pi\) | `$\pi$` |
## Usual functions and operators
| Symbol | Command |
| ----------- | ----------- |
| \(\cos\) | `$\cos$` |
| \(\sin\) | `$\sin$` |
| \(\lim\) | `$\lim$` |
| \(\exp\) | `$\exp$` |
| \(\to\) | `$\to$` |
| \(\in\) | `$\in$` |
| \(\forall\) | `$\forall$` |
| \(\exists\) | `$\exists$` |
| \(\equiv\) | `$\equiv$` |
| \(\sim\) | `$\sim$` |
| \(\approx\) | `$\approx$` |
| \(\times\) | `$\times$` |
| \(\le\) | `$\le$` |
| \(\ge\) | `$\ge$` |
## Exponents and indices
| Symbol | Command |
| ----------- | ----------- |
| \(k_{n+1}\) | `$k_{n+1}$` |
| \(n^2\) | `$n^2$` |
| \(k_n^2\) | `$k_n^2$` |
## Fractions, binomial coefficients, square roots, …
| Symbol | Command |
| ----------------------------- | ----------------------------- |
| \(\frac{4z^3}{16}\) | `$\frac{4z^3}{16}$` |
| \(\frac{n!}{k!(n-k)!}\) | `$\frac{n!}{k!(n-k)!}$` |
| \(\binom{n}{k}\) | `$\binom{n}{k}$` |
| \(\frac{\frac{x}{1}}{x - y}\) | `$\frac{\frac{x}{1}}{x - y}$` |
| \(^3/_7\) | `$^3/_7$` |
| \(\sqrt{k}\) | `$\sqrt{k}$` |
| \(\sqrt[n]{k}\) | `$\sqrt[n]{k}$` |
## Summations and integrals
| Symbol | Command |
| ---------------------------------------------- | ---------------------------------------------- |
| \(\sum_{i=1}^{10} t_i\) | `$\sum_{i=1}^{10} t_i$` |
| \(\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x\) | `$\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x$` |
## Outfits ☺
| Symbol | Command |
| ----------------------- | ----------------------- |
| \(\hat{a}\) | `$\hat{a}$` |
| \(\bar{a}\) | `$\bar{a}$` |
| \(\dot{a}\) | `$\dot{a}$` |
| \(\ddot{a}\) | `$\ddot{a}$` |
| \(\overrightarrow{AB}\) | `$\overrightarrow{AB}$` |
# About `markdown`
First of all, to know more about `markdown` and its extensions, you may
want to read:
- The « [Élaboration et conversion de documents avec Markdown et
Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » tutorial by
Jean-Daniel Bonjour (EPFL). A must-read in French…
- The wikipedia article on
[Markdown](https://en.wikipedia.org/wiki/Markdown#Example) provides
a good overview of the `markdown` syntax.
- Github proposes a short and efficient introduction: [Mastering
Markdown](https://guides.github.com/features/mastering-markdown/).
As we explain in the video, `github` and `gitlab` allow you to easily
edit `mardown` documents and to render them in `html`. This is quite
convenient but may be a bit cumbersome for a daily use. You may prefer
to edit these documents with a real editor and later to export them in
whichever format you may like (`html`, `pdf`, `docx`, `epub`, etc).
There are a few editors specifically designed for `markdown` (see for
example the
[Editors](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#editors) page
of the `pandoc` website) but we rather advise you to use a
general-purpose editor that is capable of handling the `markdown`
syntax. A few ones were mentioned in the beginning of the video and
additional information are available in the ["Quelques éditeurs adaptés
à l'édition
Markdown"](https://enacit1.epfl.ch/markdown-pandoc/#editeurs_markdown)
section of Jean-Daniel Bonjour's tutorial.
To convert `markdown` in an "arbitrary" other format, the best solution
today is [Pandoc](http://pandoc.org/), a software developed by John
MacFarlane, a philosopher from de Berkeley, and whose [main page is on
github](https://github.com/jgm/pandoc). J.-D. Bonjour's tutorial
provides many explanations on how to install and use `pandoc` in the
[Utilisation du convertisseur
Pandoc](https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc)
section. `pandoc` is written in Haskell and may be a bit cumbersome to
install. Therefore, we provide here a few alternative solutions:
- Some websites like <http://www.markdowntopdf.com/> or
<http://markdown2pdf.com/> allow you to convert online `markdown`
files into `pdf` files without having to install anything on your
computer.
- The [CommonMark](http://commonmark.org/) project proposes a rigorous
specification of the `markdown` syntax and converters `markdown` →
`html` / `LaTeX` written in `C` and `JavaScript`
(<https://github.com/CommonMark/CommonMark>).
- You will find on the website of [John
Gruber](https://daringfireball.net/projects/markdown/), the creator
of `markdown`, a `markdown` → `html` converter written in `perl`.
- [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) is another
`markdown` extension that provides its own `markdown` → `html`
converter written in `C`.
- [grip](https://github.com/joeyespo/grip) is a `python`-based server
that allows you to convert on the fly `markdown` documents and to
preview them with your favorite browser (this is quite useful to
avoid useless commits just for the sake of previewing when using
`github` ou `gitlab`).
The `pdf` conversion always relies on
[LaTeX](https://fr.wikipedia.org/wiki/LaTeX), which requires a
full-fledged and running LaTeX installation on your computer.
In the demo, we show how to generate a `docx` from a `markdown` document
with `Pandoc` and we explain that it is then possible to use a word
processor like `LibreOffice` to edit the resulting file. Obviously the
modifications will not be back-propagated to the original `markdown`
document. You may however want to use `Pandoc` again to convert your new
`docx` document to a new `markdown` document.
Another common strategy consists in doing most of the editing of an
article/report in `Markdown` and to export it into a `docx` (or `LaTeX`)
only in the end so as to prepare it for a camera-ready version with a
standard word processing environment (or a `LaTeX` editor).
module1/ressources/introduction_to_markdown_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Introduction à Markdown
date: Tue Feb 19 19:19:03 2019
---
Voici un aperçu rapide de la syntaxe Markdown repris d'une [présentation
de Github](https://guides.github.com/features/mastering-markdown/) ainsi
que de celles d'[Archer
Reilly](http://csrgxtu.github.io/2015/03/20/Writing-Mathematic-Fomulars-in-Markdown/).
# Table des matières <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Syntaxe](#syntaxe)
- [Headers](#headers)
- [Emphasis](#emphasis)
- [Lists](#lists)
- [Images](#images)
- [Links](#links)
- [Blockquotes](#blockquotes)
- [Inline code](#inline-code)
- [Écrire des Maths](#écrire-des-maths)
- [Lettres grecques](#lettres-grecques)
- [Fonctions et opérateurs](#fonctions-et-opérateurs)
- [Exposants et indices](#exposants-et-indices)
- [Fractions, coefficients binomiaux, racines,
…](#fractions-coefficients-binomiaux-racines-)
- [Sommes et intégrales](#sommes-et-intégrales)
- [Déguisements](#déguisements)
- [Autour de `markdown`](#autour-de-markdown)
# Syntaxe
## Headers
``` example
# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag
```
## Emphasis
``` example
*This text will be italic*
_This will also be italic_
**This text will be bold**
__This will also be bold__
_You **can** combine them_
```
## Lists
### Unordered
``` example
- Item 1
- Item 2
- Item 2a
- Item 2b
```
### Ordered
``` example
1. Item 1
2. Item 2
3. Item 3
1. Item 3a
2. Item 3b
```
## Images
``` example
![GitHub Logo](/images/logo.png)
Format: ![Alt Text](url)
```
## Links
``` example
http://github.com - automatic!
[GitHub](http://github.com)
```
## Blockquotes
``` example
As Kanye West said:
> We're living the future so
> the present is our past.
```
## Inline code
```` example
To print some text with python, you should use the `print()` function.
```
print("Hello world!")
```
````
# Écrire des Maths
Il est possible d'écrire des formules en Markdown, soit en mode
**inline** soit en mode **displayed formulas**. Dans le premier cas, les
formules sont inclues directement à l'intérieur du paragraphe courant
alors que dans le second, elles apparaissent centrées et mises en
exergue.
Le formatage de la formule est légèrement différent dans les deux cas
car pour qu'une formule s'affiche joliment sur une seule ligne, il faut
la "tasser" un peu plus que lorsqu'elle est mise en valeur.
Pour écrire une formule en mode **inline**, il faut la délimiter par un
`$` (du coup, pour écrire le symbole dollar, il faut le préfixer par un
backslash, comme ceci: `\$`) alors que pour écrire en mode
**displayed**, il faut la délimiter par un `$$`. Un petit exemple valant
mieux qu'un long discours, voici concrètement comment cela fonctionne:
``` example
Cette expression $\sum_{i=1}^n X_i$ est inlinée.
```
Cette expression \(\sum_{i=1}^n X_i\) est inlinée.
``` example
Cette expression est mise en valeur:
$$\sum_{i=1}^n X_i$$
```
Cette expression est mise en valeur:
\[\sum_{i=1}^n X_i\]
Nous vous présentons par la suite une sélection de symboles et de
commandes courantes. En fait, à peu près tout ce qui est classique dans
le langage LaTeX peut être utilisé pourvu que vous délimitiez bien avec
un `$`. Pour d'autres exemples plus complets jetez un coup d'œil à ces
[exemples de James H.
Steiger](http://www.statpower.net/Content/310/R%2520Stuff/SampleMarkdown.html).
## Lettres grecques
| Symbole | Commande |
| ---------- | ---------- |
| \(\alpha\) | `$\alpha$` |
| \(\beta\) | `$\beta$` |
| \(\gamma\) | `$\gamma$` |
| \(\Gamma\) | `$\Gamma$` |
| \(\pi\) | `$\pi$` |
## Fonctions et opérateurs
| Symbole | Commande |
| ----------- | ----------- |
| \(\cos\) | `$\cos$` |
| \(\sin\) | `$\sin$` |
| \(\lim\) | `$\lim$` |
| \(\exp\) | `$\exp$` |
| \(\to\) | `$\to$` |
| \(\in\) | `$\in$` |
| \(\forall\) | `$\forall$` |
| \(\exists\) | `$\exists$` |
| \(\equiv\) | `$\equiv$` |
| \(\sim\) | `$\sim$` |
| \(\approx\) | `$\approx$` |
| \(\times\) | `$\times$` |
| \(\le\) | `$\le$` |
| \(\ge\) | `$\ge$` |
## Exposants et indices
| Symbole | Commande |
| ----------- | ----------- |
| \(k_{n+1}\) | `$k_{n+1}$` |
| \(n^2\) | `$n^2$` |
| \(k_n^2\) | `$k_n^2$` |
## Fractions, coefficients binomiaux, racines, …
| Symbole | Commande |
| ----------------------------- | ----------------------------- |
| \(\frac{4z^3}{16}\) | `$\frac{4z^3}{16}$` |
| \(\frac{n!}{k!(n-k)!}\) | `$\frac{n!}{k!(n-k)!}$` |
| \(\binom{n}{k}\) | `$\binom{n}{k}$` |
| \(\frac{\frac{x}{1}}{x - y}\) | `$\frac{\frac{x}{1}}{x - y}$` |
| \(^3/_7\) | `$^3/_7$` |
| \(\sqrt{k}\) | `$\sqrt{k}$` |
| \(\sqrt[n]{k}\) | `$\sqrt[n]{k}$` |
## Sommes et intégrales
| Symbole | Commande |
| ---------------------------------------------- | ---------------------------------------------- |
| \(\sum_{i=1}^{10} t_i\) | `$\sum_{i=1}^{10} t_i$` |
| \(\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x\) | `$\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x$` |
## Déguisements
| Symbole | Commande |
| ----------------------- | ----------------------- |
| \(\hat{a}\) | `$\hat{a}$` |
| \(\bar{a}\) | `$\bar{a}$` |
| \(\dot{a}\) | `$\dot{a}$` |
| \(\ddot{a}\) | `$\ddot{a}$` |
| \(\overrightarrow{AB}\) | `$\overrightarrow{AB}$` |
# Autour de `markdown`
Tout d'abord, pour aller plus loin avec `markdown` et ses extensions /
ramifications :
- Le didacticiel « [Élaboration et conversion de documents avec
Markdown et Pandoc](https://enacit1.epfl.ch/markdown-pandoc/) » de
Jean-Daniel Bonjour (EPFL), précis, complet, concis, en français ;
un vrai bonheur \!
- L'article [Markdown](https://en.wikipedia.org/wiki/Markdown#Example)
de wikipedia en anglais contient un bon pense-bête sur la syntaxe
`markdown`.
- Github propose un court et efficace didacticiel (en anglais) :
[Mastering
Markdown](https://guides.github.com/features/mastering-markdown/).
Comme nous l'illustrons dans la « film d'écran » (*screencast*),
l'éditeur de texte des dépôts `github` et `gitlab` permet d'interpréter
/ transformer à la demande un fichier `mardown` en un fichier `html`.
C'est à la fois agréable et pratique, mais ce n'est pas une solution
pour une utilisation quotidienne de `markdown`, pour cela, il est plus
efficace d'éditer son texte, avec un éditeur de texte, sur son
ordinateur, avant de « l'exporter » dans un format comme `html`, `pdf`,
`docx`, `epub`, etc. Il existe des éditeurs plus ou moins spécialisés
pour `markdown`, certains sont indiqués sur la page
[Editors](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#editors) du
site de `pandoc`, mais nous préconisons clairement l'emploi d'un éditeur
de texte « généraliste » capable de reconnaître la syntaxe `markdown`.
Nous en avons indiqué en début de séquence et on pourra trouver des
informations complémentaires dans la section [Quelques éditeurs adaptés
à l'édition
Markdown](https://enacit1.epfl.ch/markdown-pandoc/#editeurs_markdown) du
didacticiel de Jean-Daniel Bonjour.
Pour convertir un fichier `markdown` en un format « arbitraire », la
solution à ce jour la plus complète est [Pandoc](http://pandoc.org/),
logiciel développé par John MacFarlane, un philosophe de Berkeley (le
site [github](https://github.com/jgm/pandoc)). En plus du site de
`Pandoc`, le didacticiel de J.-D. Bonjour donne de nombreuses
explications sur comment installer et utiliser `pandoc` dans la section
[Utilisation du convertisseur
Pandoc](https://enacit1.epfl.ch/markdown-pandoc/#commande_pandoc). Comme
`pandoc` – écrit en Haskell – peut être parfois un peu difficile à
installer, nous indiquons maintenant quelques solutions alternatives :
- Des sites comme <http://www.markdowntopdf.com/> et
<http://markdown2pdf.com/> permettent de convertir en ligne un
fichier `markdown` en un fichier `pdf`.
- Le projet [CommonMark](http://commonmark.org/) propose, en plus
d'une spécifications plus rigoureuse de la syntaxe `markdown`, des
convertisseurs `markdown` → `html` / `LaTeX` (et plus) écris en `C`
et en `JavaScript` (<https://github.com/CommonMark/CommonMark>).
- Le site de [John
Gruber](https://daringfireball.net/projects/markdown/), le créateur
de `markdown`, fournit un convertisseur `markdown` → `html` écrit en
`perl`.
- [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) est une
autre extension de `markdown` qui vient avec son convertisseur
`markdown` → `html` écrit en `C`.
- [grip](https://github.com/joeyespo/grip) est un serveur écrit en
`python` qui permet de convertir et visualiser à la volée des
fichiers `markdown` avec son navigateur (très utile pour éviter
d'avoir à faire des « commits » en grande quantité lorsqu'on écrit
de tels fichiers pour un dépôt `github` ou `gitlab`).
La conversion en `pdf` passe toujours par
[LaTeX](https://fr.wikipedia.org/wiki/LaTeX) ce qui nécessite d'avoir
une version complète et à jour de ce logiciel sur sa machine.
Dans la petite démonstration, nous montrons comment générer un fichier
`docx` à partir d'un fichier `md` avec `Pandoc` et nous soulignons qu'il
est alors possible d'utiliser un traitement de texte comme `LibreOffice`
pour modifier le fichier obtenu. Il est clair que si des modifications
sont apportées au `docx` elle en seront pas (automatiquement) propagées
au `md`. Il faudra utiliser `Pandoc` pour cela et effectuer une
conversion de `docx` vers `md` (et seules les éléments du format `docx`
qui existent en `md` seront conservés).
Une stratégie qui est souvent employée et qui fonctionne bien en
pratique consiste à faire le gros du travail de rédaction d'un article
ou d'un mémoire en `Markdown`. La rédaction terminée, le fichier est
exporté au format `docx` (ou `LaTeX`) et des ajustements de mise en page
sont alors effectués avec un logiciel de traitement de texte (ou un
éditeur `LaTeX`).
module1/ressources/sequence1_fr.md deleted 100644 → 0
View file @ 8986dad7
# Table des matières
1. [Notes et références sur la séquence 1 : « Nous utilisons tous des cahiers de notes »](#org1a7eead)
1. [Manuscrits annotés](#org6ff88dc)
2. [Armoires à notes de Placcius et Leibniz](#org71f150b)
3. [La préface de « L'île des pingouins » d'Anatole France](#orgd8056e5)
4. [Les livres de bord](#org30bb343)
5. [Un absent : le cahier de laboratoire classique](#orge788c0a)
<a id="org1a7eead"></a>
# Notes et références sur la séquence 1 : « Nous utilisons tous des cahiers de notes »
<a id="org6ff88dc"></a>
## Manuscrits annotés
En guise d'entrée dans l'univers des manuscrits annotés, je fais suivre une petite sélection de passages du premier chapitre de « LA PAGE. DE L'ANTIQUITÉ À L'ÈRE DU NUMÉRIQUE » d'Anthony Grafton (Hazan, 2012) :
Par le mouvement même de sa plume sur la page, il est clair que
Casaubon maîtrise tout ce qu'il lit. Constamment, il souligne des
mots et des expressions, il note en marge des mots clés et des résumés
montrant qu'il a lu attentivement, même quand, précise-t-il dans son
journal intime, il étudie en une journée quarante à cinquante pages
in-folio de grec émaillées de nombreuses abréviations. Les passages
plus importants donnent lieu en marge à des commentaires plus
longs. Sur les pages de titre, Casaubon porte très souvent — un peu
comme Montaigne — un jugement global sur la valeur de l'ouvrage.
Par ailleurs, il note ses réflexions dans des carnets, ou prend
des notes sur des textes qu'il ne peut pas acheter. Tels qu'ils sont
réunis dans sa bibliothèque, ses livres représentent une vie entière de
lecture que l'on peut reconstituer au fil des pages.
Pages 32 et 33, à propos d'[Isaac Casaubon](https://fr.wikipedia.org/wiki/Isaac_Casaubon) (1559-1614).
Pourtant, Harvey a laissé beaucoup plus que cela, et notamment
des traces des ses lectures sous forme de plus d'une centaine de livres
couverts d'annotations magnifiquement écrites de sa belle écriture
italique — en plus des cahiers dans lesquels il notait des extraits.
Manifestement, Harvey considérait la lecture comme sa profession,
et il en a fait aussi un art. Décennie après décennie, il couche ses
pensées sur l'histoire dans une édition in-folio de 1555 de l'Histoire
romaine de Tite-Live. Ses notes, en latin pour la plupart, parcourent
les marges, se répandent entre les chapitres et remplissent
des feuilles volantes, prenant un aspect particulièrement érudit et
assez rébarbatif.
Pages 35 et 36, à propos de [Gabriel Harvey](https://en.wikipedia.org/wiki/Gabriel_Harvey) (1545-1630).
... Mais dans l'exemplaire de travail qui subsiste du
texte, l'édition de base de 1549, il [Casaubon] introduit tant d'annotations
précises que les catalogueurs de la Bibliothèque bodléienne, qui n'étaient
pas rompus à la rhétorique, ont classé ce livre imprimé parmi les manuscrits.
Page 40.
<a id="org71f150b"></a>
## Armoires à notes de Placcius et Leibniz
J'ai trouvé cet exemple dans les travaux d'[Ann Blair](https://projects.iq.harvard.edu/ablair) comme « [The Rise of Note-Taking in Early Modern Europe](https://dash.harvard.edu/handle/1/4774908) » et son livre « [TOO MUCH TO KNOW. Managing Scholarly Information before the Modern Age](https://yalebooks.yale.edu/book/9780300165395/too-much-know) », publié chez *Yale University Press* en 2011.
<a id="orgd8056e5"></a>
## La préface de « L'île des pingouins » d'Anatole France
Étant très loin de connaître Anatole France sur le bout des doigts, j'ai trouvé la référence citée dans le remarquable article de Keith Thomas publié par la *London Review of Books*, [le 10 juin 2010](https://www.lrb.co.uk/v32/n11/keith-thomas/diary). Cet article (en anglais) décrit et discute le travail concret de prise de notes par un historien, il est de plus très bien écrit et plein d'anecdotes.
<a id="org30bb343"></a>
## Les livres de bord
Je remercie Joël Caselli de m'avoir aidé à interpréter le contenu du livre de bord d'Éric Tabarly.
Le projet européen de reconstruction des climats des océans atlantique et indien (et non pacifique comme je le dis dans le cours !) : [*Climatological Database for the World's Oceans 1750-1850*](http://webs.ucm.es/info/cliwoc/) ; dispose d'un site internet très intéressant (mais en anglais).
On trouvera des citations abondantes (et effrayantes) de livres de bord de navires négriers dans le livre de Marcus Rediker « À bord du négrier : Une histoire atlantique de la traite » (disponible en édition de poche).
<a id="orge788c0a"></a>
## Un absent : le cahier de laboratoire classique
Je traduis ici la section 6.2 *Notebooks and Records* du remarquable livre de E. Bright Wilson *An Introduction to Scientific Research* réimprimé par Dover.
Il est difficile de concevoir un cahier de laboratoire parfait et il est malheureusement rare d'en trouver un qui soit même à peu près satisfaisant ; la conservation d'une trace écrite du travail effectué est néanmoins une source majeure d'efficacité. Il y aura forcément des gens opposés à un ensemble de règles fixes, mais cela sera probablement plus rare pour le rituel de garder un cahier que sur d'autres sujets. Par conséquent, un ensemble de règles qui sont généralement considérées comme satisfaisantes, voire même essentielles, seront quelque peu dogmatiquement énoncées.
De grandes découvertes ont été retardées en raison d'une négligente tenue des traces écrites. L'astronome Le Monnier est ainsi supposé avoir observé la planète Uranus à plusieurs reprises &#x2013; avant que son identification comme planète ait été annoncée par Herschel &#x2013;, mais a décidé qu'elle était une étoile fixe. Cela s'explique probablement en partie par le fait qu'il a écrit ses mesures sur des morceaux de papier, y compris un sac en papier contenant à l'origine de la poudre pour cheveux !
Les cahiers de laboratoire doivent être solidement reliés, d'une taille approximative de 20 x 25 cm, avec des pages numérotées. Les feuilles séparées sont trop facilement perdues pour être satisfaisantes, d'autant plus qu'un cahier de laboratoire subit souvent un traitement un peu rude avec peut-être des projections occasionnelles d'acide [c'est un physico-chimiste qui écrit]. Le cas de mesures répétées constitue une exception où une ébauche spéciale imprimée est souvent utile si un bon système est établi pour collecter et relier les feuilles séparées. Les pages avec des lignes sont généralement utilisées, mais il s'agit d'une question de goût personnel, et certaines préfèrent des pages blanches ou à carreaux. Un tampon en caoutchouc peut être utilisé pour fournir des en-têtes pour les entrées les plus communes.
Les données doivent être entrées directement dans le cahier au moment de l'observation. Il est intolérable d'utiliser sa mémoire ou des fragments de papier pour l'enregistrement primaire, du fait de l'inévitabilité des erreurs et des pertes. Il devrait donc y avoir une bonne place pour le cahier à coté du poste de travail, et l'expérimentateur ne devrait jamais être sans son cahier lorsqu'il est en action.
Les données doivent être enregistrées à l'encre, de préférence une encre permanente, un buvard peut être pratique. Sinon, la trace écrite est trop éphémère. Les cahiers sont soumis à une utilisation intensive et les écritures au crayons se détériorent trop rapidement. Lorsque le cahier peut être utilisé comme preuve pour un brevet, l'usage de l'encre s'impose.
Des graphiques approximatifs et qualitatifs peuvent être dessinés directement, mais les graphiques précis sont généralement préparés avec le papier graphique du type le plus approprié [pensez au papier millimétré]. Ils sont ensuite soigneusement collés dans le cahier, une page vierge étant découpée afin de compenser l'épaisseur ajoutée.
Les cahiers doivent porter le nom de l'utilisateur et les dates couvertes. [&#x2026;]. Les huit ou dix premières pages devraient être réservées pour une table des matières. Il s'agit de lignes ajoutées chronologiquement pour chaque série d'expériences similaires, ainsi que la référence de la page. La table des matières est extrêmement utile pour trouver des éléments plus tard et est très simple à suivre. Un index au dos du cahier est avantageux mais pas indispensable.
Chaque élément devrait être datée et, si plusieurs personnes utilisent un cahier (généralement pas recommandé), paraphé. Le contenu ne devrait pas inscrit de façon trop dense sur les pages ; le papier est bon marché par rapport aux autres dépenses de recherche.
La principale difficulté est de décider ce qu'il faut écrire dans le cahier. Évidemment, on entre les résultats numériques et les valeurs des variables indépendantes telles que la température, la composition ou la pression qui sont directement pertinentes. Il est également nécessaire d'avoir un système d'entrées ou de références afin que, plus tard, il soit possible de dire quel appareil a été utilisé et dans quelles circonstances. Une description assez complète de l'appareil devrait être conservée. Ensuite, lorsque des modifications sont apportées à l'appareil, elles doivent être décrites immédiatement dans le cahier. Il devrait également être possible de retracer la source des courbes d'étalonnage, des corrections, etc., qui étaient appropriées aux données d'un jour donné. Il est utile que les exigences relatives à l'écriture d'un article, d'une thèse ou d'un livre soient gardées à l'esprit. Une telle tâche, une fois effectuée, entraîne généralement la résolution solennelle de garder un cahier plus détaillé dans le futur. Essayer de comprendre le cahier de notes de quelqu'un d'autre constitue aussi un exercice hautement salutaire. Toutes les références aux appareils, aux lieux, aux horaires, aux livres, aux articles, aux graphiques et aux personnes devraient être suffisamment explicites pour être compréhensibles des années plus tard. **Il devrait être possible de prendre chaque article scientifique et de montrer exactement où chaque figure, description ou déclaration est justifiée par des observations originales dans le cahier de laboratoire, et exactement pourquoi les nombres final et original diffèrent, si tel est le cas**.
Un énoncé du but de chaque expérience et un résumé des conclusions obtenues rendent le cahier beaucoup plus utile.
Les croquis, dessins et diagrammes sont essentiels. Comme tant d'observations sont visuelles, *il est important de noter ce qui est réellement vu, y compris des éléments qui ne sont pas entièrement compris lors de leur observation*.
Les expériences mauvaises ou non prometteuses, même celles considérées comme des échecs, devraient être entièrement enregistrées. Elles représentent un effort qui ne doit pas être gaspillé, car souvent quelque chose peut être récupéré, même si ce n'est qu'une connaissance de ce qu'il ne faut pas faire.
Les données doivent toujours être entrées dans leur forme la plus primaire, et non après un calcul ou une transformation. Si c'est le rapport de deux observations qui est intéressant, mais si les deux nombres sont effectivement observés, les deux nombres doivent être enregistrés. Si le poids précis d'un objet est important, les poids d'équilibrage individuels utilisés et leur identification devraient être inclus, c'est-à-dire le numéro de série de leur boîte. Dans le cas contraire, il devient impossible d'appliquer ultérieurement des corrections d'étalonnage ou de modifier les corrections si de nouvelles valeurs apparaissent. Naturellement, ce détail n'est pas nécessaire si seulement un poids approximatif est impliqué. La forme tabulaire est la meilleure pour les données numériques. Les unités doivent être notées.
Lorsque des brevets sont impliquées, il peut être souhaitable d'authentifier les pages des cahiers à intervalles réguliers. Le témoin devrait être quelqu'un qui comprend le contenu mais qui n'est pas impliqué dans la recherche. Un contenu ajouté ultérieurement à une page devrait l'être dans une encre de couleur différente, et toutes les modifications devraient être paraphées, authentifiées et datées si elles sont susceptibles d'être importantes. Les entreprises industrielles font ainsi généralement respecter leurs propres règles en matière de cahiers de laboratoire.
**Numéros d'identification**. Il est stupide de consacrer du temps et de l'argent à des enregistrements de différents types [&#x2026;] si ceux-ci sont ensuite perdus ou mélangés. Tout enregistrements qui ne peut être inclut directement dans le cahier de notes devraient porter une identification complète indélébile. Un système simple qui a fait ses preuves consiste à écrire à l'encre sur chaque enregistrement un symbole identifiant le cahier, puis le numéro de page sur lequel les données auxiliaires sont enregistrées. Si plus d'un enregistrement sont mentionnés sur une page du cahier, des lettres ou des chiffres supplémentaires peuvent être ajoutés. Ainsi, EBW II 85c identifie le troisième enregistrement discuté à la page 85 du deuxième cahier EBW. C'est mieux qu'un numéro de série qui ne dit pas, sans clé supplémentaire, où chercher la description le concernant dans le cahier.
Un bon système de classement est indispensable pour tous les films, les photographies, les schémas, les graphiques, les diagrammes de circuit, les dessins, les plans, etc. Il est plus difficile de concevoir des méthodes de dépôt satisfaisantes pour des matériaux très petits ou très grands. Les premiers sont facilement perdus et les dernier très volumineux. [&#x2026;]
Il est important d'archiver les dessins et les plans à partir desquels les appareils utilisés ont été construits, même si ces dessins sont grossiers. Ils doivent être datés, paraphés et étiquetés ; en fait, tout morceau de papier contenant une information utile devrait être marqué de la sorte. Lorsqu'un équipement électronique ou autre est fabriqué, son diagramme doit être soigneusement préparé et entièrement étiqueté avec toutes les constantes. L'appareil doit porter un numéro de série qui apparaît également sur ce diagramme. Lorsque des modifications sont apportées, celles-ci doivent être indiquées sur le schéma et datées ou un diagramme révisé et daté doit être préparé. L'ancien ne doit pas être obscurci ou jeté, car il peut être nécessaire pour expliquer des données antérieures, considérées ultérieurement comme étranges. [&#x2026;]
Le but de toute cette pratique de prise de notes est de préserver la valeur [le temps et les moyens humains et matériels investis dans la recherche]. Elle devrait être soigneusement conçus pour s'adapter aux conditions de chaque laboratoire et devraient être adéquate mais pas trop élaborés. **Si l'on exige trop de la nature humaine, le système ne fonctionnera pas**.
module1/ressources/sequence2_fr.md deleted 100644 → 0
View file @ 8986dad7
# Table des matières
1. [Notes et références sur la séquence 2 : « Un aperçu historique de la prise de notes »](#org382d650)
1. [Références générales](#orgd6af51b)
2. [Sur les tablettes de cires](#org51b3800)
3. [Sur le passage du rouleau (*volumen*) au codex](#orga427d5c)
4. [Sur Eusèbe de Césarée](#org37570fe)
5. [Parallèle chinois](#orgaaa2791)
6. [Retour sur l'armoire à notes](#orga5c9112)
7. [L'index et John Locke](#orgae153c1)
<a id="org382d650"></a>
# Notes et références sur la séquence 2 : « Un aperçu historique de la prise de notes »
<a id="orgd6af51b"></a>
## Références générales
En plus des deux livres déjà cités (en séquence 1) :
- « LA PAGE. DE L'ANTIQUITÉ À L'ÈRE DU NUMÉRIQUE » d'Anthony Grafton (Hazan, 2012) ;
- « [TOO MUCH TO KNOW. Managing Scholarly Information before the Modern Age](https://yalebooks.yale.edu/book/9780300165395/too-much-know) », d'Ann Blair publié chez *Yale University Press* en 2011 ;
j'ai utilisé :
- « L'histoire du livre » de Frédéric Barbier ;
- le remarquable site de Jacques Poitou, [langages écritures typographies](http://j.poitou.free.fr/pro/index.html) ;
- le site [l'aventure des écritures](http://classes.bnf.fr/ecritures/) de la BNF ;
- le catalogue de l'exposition de la BNF « Tous les savoirs du monde : Encyclopédies et bibliothèques de Sumer au XXIème siècle » ;
- « [Du papyrus à l'hypertexte](http://litmedmod.ca/sites/default/files/pdf/vandendorpe-papyrusenligne_lr.pdf) » de Christian Vandendorpe (La Découverte, 1999).
<a id="org51b3800"></a>
## Sur les tablettes de cires
Voir le site de Jacques Poitou (d'où les illustrations sont empruntées) et le livre de Frédéric Barbier, « L'histoire du livre ».
<a id="orga427d5c"></a>
## Sur le passage du rouleau (*volumen*) au codex
Voir le livre de Frédéric Barbier, celui d'Anthony Grafton.
Le *volumen* est un livre à base de feuilles de papyrus collées les unes aux autres et qui s'enroule sur lui-même. Il a été créé en Égypte vers 3000 av. J.-C. Le texte est rédigé en colonnes parallèles assez étroites. C'est le support du texte par excellence durant les trente siècles précédant notre ère, d'abord en Égypte, puis dans tout le monde méditerranéen.
Comme l'explique Frédéric Barbier : « La forme du *volumen* impose une pratique de lecture complexe : il faut dérouler (*explicare*) et enrouler en même temps, ce qui interdit par exemple, de travailler simultanément sur plusieurs rouleaux (un texte et son commentaire) ou de prendre des notes, impose une lecture suivie et empêche la simple consultation. »
Le *volumen* n'est clairement pas adapté à une lecture « nomade » ; imagine-t-on Ulysse partant pour son Odyssée avec les 24 *volumen* de l'Iliade ?
Le *volumen* est à l'origine du terme « volume » dans un « livre en plusieurs volumes » comme dans la désignation du concept géométrique.
Le passage au codex repose sur deux innovations :
- la collection des tablettes de cires en « groupes reliés » ;
- la généralisation du parchemin (peau, généralement, de mouton spécialement préparée) au détriment du papyrus. Cette généralisation résulte une lutte pour l'hégémonie culturelle entre deux descendants de généraux d'Alexandre le Grand, en effet d'après Pline l'ancien : [Ptolémé Épiphane](https://fr.wikipedia.org/wiki/Ptol%C3%A9m%C3%A9e_V) d'Alexandrie cherchait à empêcher [Eumène II](https://fr.wikipedia.org/wiki/Eum%C3%A8ne_II) d'établir une bibliothèque à Pergame (au 2e siècle avant J.-C.) et avait interdit l'exportation du papyrus (produit exclusivement en Égypte), ce qui incita Eumène à chercher un substitut qui devint le parchemin.
Le remplacement du rouleau par le codex aura des conséquences majeures sur l'organisation du livre ainsi que sur la façon de lire et il permettra le développement ultérieur de l'imprimerie.
La principale révolution introduite par le codex est la notion de page. Grâce à elle, le lecteur peut accéder de manière directe à un chapitre ou à un passage du texte, alors que le rouleau impose une lecture continue. **Les mots ne sont de plus pas séparés par des espaces**. Comme l'écrit Collette Sirat : « Il faudra vingt siècles pour qu’on se rende compte que l’importance primordiale du codex pour notre civilisation a été de permettre la lecture sélective et non pas continue, contribuant ainsi à l’élaboration de structures mentales où le texte est dissocié de la parole et de son rythme. »
Au fil des siècles, le codex — qu'on désigne le plus souvent comme un manuscrit — va évoluer et se donner peu à peu les attributs du livre moderne : séparation entre les mots (VIIe siècle), début de ponctuation (VIIIe siècle), table des matières, titre courant, marque de paragraphe (XIe siècle), pagination, index (XIIIe siècle), etc.
Un point intéressant : le contenu de la Thora est « fixé » avant l'apparition du codex et, aujourd'hui encore, la Thora est écrite sur des *volumen* (dans les synagogues au moins). La religion chrétienne se développe en même temps que le codex, adopte ce support et le répand ; elle ne donnera jamais au *volumen* un statut « supérieur », pas plus que ne le fera la religion musulmane.
<a id="org37570fe"></a>
## Sur Eusèbe de Césarée
Pour en savoir plus sur [Eusèbe de Césarée](https://fr.wikipedia.org/wiki/Eus%C3%A8be_de_C%C3%A9sar%C3%A9e), consultez le passionnant deuxième chapitre du livre d'Anthony Grafton.
<a id="orgaaa2791"></a>
## Parallèle chinois
Comme je le dis, mon inculture fait que je ne rends pas justice aux contributions chinoises, musulmanes, précolombienne, etc. J'essaierai de combler cette énorme lacune pour les seconde version du CLOM&#x2026;
Ce que je dis sur le passage du volumen au codex accompagné d'un développement des « outils de navigation » (index, table des matières, etc) en Chine lors du développement de leishus vient du bouquin d'Ann Blair (p. 31) qui cite un article de Susan Cherniack, « Book Culture and Textual Transmission in Sung China », *Harvard Journal of Asiatic Studies* Vol. 54, No. 1 (Jun., 1994), pp. 5-125.
<a id="orga5c9112"></a>
## Retour sur l'armoire à notes
Nous revenons sur le « bout de papier » ou la fiche comme support de note. L'inconvénient est que le bout de papier ou la fiche se perdent facilement et ne servent à rien s'ils ne sont pas **classés** en plus d'être rangés. Problème résolu par l'armoire de Placcius. D'une certaine façon, sa conception fait qu'on accède à son contenu par l'index.
L'avantage est que les notes peuvent être réorganisées si elles contiennent des information sur plusieurs sujets. Elle peuvent aussi être directement collées dans un livre lors de la composition d'un florilège ou d'un ouvrage de synthèse.
Ce dernier procédé était très couramment employé par les humanistes et les érudit de la renaissance et du début de la période moderne. [Conrad Gessner](https://fr.wikipedia.org/wiki/Conrad_Gessner) (1516-1565) était un champion de cette technique ; il obtenait même parfois ses fiches en découpant les pages des livres. Encore une fois, ne faites pas cela avec les livres de bibliothèques !
<a id="orgae153c1"></a>
## L'index et John Locke
Sur l'origine de l'index, on pourra lire l'article de Jean Berger : [Indexation, Memoire, pouvoir et representations au seuil du XIIe siecle : La redecouverte des feuillets de tables du Liber De Honoribus, premier cartulaire de la collegiale Saint-Julien de Brioude](https://www.theindexer.org/files/25-2-berger.pdf), *The Indexer*.
La méthode de John Lock est expliquée dans l'article *Indexing commonplace books: John Locke’s method* d'Alan Walker, [The Indexer](https://www.theindexer.org/issues/query.php?vol=22&iss=3), vol. 22, p. 114-118, 2001.
Sur [John Locke](https://fr.wikipedia.org/wiki/John_Locke) (1632-1704) « papa du libéralisme » et actionnaire de la *Royal African Company* principale compagnie négrière britannique, voir l'article [Wikipedia](https://en.wikipedia.org/wiki/John_Locke#Constitution_of_Carolina) (en anglais) et le livre « Contre-histoire du libéralisme » de Domenico Losurdo (La Découverte / Poche, 2014, p. 34-36).
module1/ressources/sequence3_fr.md deleted 100644 → 0
View file @ 8986dad7
# Table des matières
1. [Notes et références sur la séquence 3 : « Du fichier texte au langage de balisage léger »](#orge633e7c)
1. [Fichier texte et éditeur de texte](#org8baa6c7)
2. [Le cas du fichier `PDF` ouvert avec un éditeur de texte](#org66a1b0c)
3. [Sur l'UTF-8](#org366381c)
<a id="orge633e7c"></a>
# Notes et références sur la séquence 3 : « Du fichier texte au langage de balisage léger »
<a id="org8baa6c7"></a>
## Fichier texte et éditeur de texte
Une définition plus technique (et moins circulaire !) du fichier texte se trouve sur [la page wikipédia](https://fr.wikipedia.org/wiki/Fichier_texte) consacrée au sujet. Pour plus de détails sur les éditeurs de texte, voir aussi la [page wikipédia correspondante](https://fr.wikipedia.org/wiki/%C3%89diteur_de_texte).
Un logiciel de « [traitement de texte](https://fr.wikipedia.org/wiki/Traitement_de_texte) » est plus sophistiqué qu'un simple éditeur de texte ; il permet de faire plus, ce qui sous entend qu'il peut aussi ouvrir et manipuler des fichiers textes.
\*Attention\* : le format « natif » des traitements de texte est rarement un format texte. Les fichiers `doc` et `docx` de `Word` et `odt` de `LibreOffice` *ne sont pas des fichiers textes*.
<a id="org66a1b0c"></a>
## Le cas du fichier `PDF` ouvert avec un éditeur de texte
Dans le cours filmé, j'utilise l'exemple du [PDF](https://en.wikipedia.org/wiki/Portable_Document_Format) — je donne l'adresse de la page wikipedia en anglais, bien plus complète que celle en français — ouvert avec un éditeur de texte pour montrer que le fichier ne peut pas être visualisé avec un tel logiciel, il faut un logiciel de rendu dédié comme `Adobe Reader`, `Evince`, `MuPDF`, `Aperçu`,&#x2026; Vous remarquez néanmoins que le début du fichier contient du texte (la première ligne nous apprend que le fichier utilise la version 1.3 du format `PDF`). Cette partie au format texte du fichier contient les méta-données — qui ne sont pas montrées, en tout cas pas directement, par les logiciels de rendu. Ces méta-données sont (en partie) au format [XMP](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) (*Extensible Metadata Platform*), nous y reviendrons dans la cinquème séquence.
<a id="org366381c"></a>
## Sur l'UTF-8
Une table des symboles UTF-8, avec leur code se trouve à l'adresse : <http://www.utf8-chartable.de/>. C'est pratique pour insérer un symbole pas très courant comme la lettre « TLO » : Ꮰ de la langue cherokee, ou le symbole mathématique ∀, « pour tout ».
Pour ceux qui doivent souvent utiliser des lettres grecs (par exemple pour écrire des équations), il est possible sous Linux de (re)définir des combinaisons de touches pour générer directement les dites lettres. Ces combinaisons sont définies dans le fichier `.XCompose`, le début de mon fichier contient :
# On charge la base de donnée de Compose la plus complète en UTF-8
include "/usr/share/X11/locale/en_US.UTF-8/Compose"
# espace insécable fine
<Multi_key> <Multi_key> <Space> : " " U202F
# Lettres greques
<Multi_key> <space> <a> : "α" Greek_alpha
<Multi_key> <space> <A> : "Α" Greek_ALPHA
<Multi_key> <space> <b> : "β" Greek_beta
<Multi_key> <space> <B> : "Β" Greek_BETA
<Multi_key> <space> <g> : "γ" Greek_gamma
<Multi_key> <space> <G> : "Γ" Greek_GAMMA
<Multi_key> <space> <d> : "δ" Greek_delta
<Multi_key> <space> <D> : "Δ" Greek_DELTA
<Multi_key> <space> <e> : "ε" Greek_epsilon
<Multi_key> <space> <E> : "Ε" Greek_EPSILON
<Multi_key> <space> <z> : "ζ" Greek_zeta
<Multi_key> <space> <Z> : "Ζ" Greek_ZETA
<Multi_key> <space> <h> : "η" Greek_eta
J'ai en plus redéfini la « <Multi<sub>key</sub>> » pour qu'elle corresponde à la touche « impression d'écran » de mon clavier. Pour apprendre à redéfinir des touches, consultez : <https://wiki.archlinux.org/index.php/Keyboard_configuration_in_Xorg#Configuring_compose_key>.
module1/ressources/sequence5_fr.md deleted 100644 → 0
View file @ 8986dad7
# Table des matières
1. [Notes et références sur la séquence 5 : « Les étiquettes et les logiciels d'indexation pour s'y retrouver »](#orga408bd6)
1. [La structure de la séquence](#org71a0671)
2. [La citation de Leibniz](#org2811460)
3. [Rechercher avec un éditeur de texte](#org56ad7e5)
4. [Recherche avec index construit « à la main » sur des cahiers de notes](#org5860004)
5. [Recherche avec index « matérialisés »](#orgfbae55d)
6. [Vers les outils « sophistiqués » de l'informatique](#org648d1fa)
7. [Les moteurs de recherche de bureau](#org2570670)
8. [Pourquoi des étiquettes](#org6714af0)
9. [Les métadonnées](#org987f9e0)
1. [Fichiers images](#org86d9232)
2. [Fichiers `PDF`](#orgca6fceb)
3. [Fichiers audios](#org87a2419)
<a id="orga408bd6"></a>
# Notes et références sur la séquence 5 : « Les étiquettes et les logiciels d'indexation pour s'y retrouver »
<a id="org71a0671"></a>
## La structure de la séquence
Nous revenons ici sur le problème de l'indexation, pas tant sur l'indexation d'un document unique que sur l'indexation de documents multiples dans des formats divers :
- comme nous l'avons déjà affirmé, prendre des notes abondantes et détaillées n'est utile que si nous pouvons retrouver les informations qu'elles contiennent quand nous en avons besoin ;
- pour des notes contenues dans un seul fichier texte, la fonction de recherche de notre éditeur favori nous permet généralement d'aller assez loin ;
- pour des notes manuscrites contenues dans un cahier, la méthode de Locke — que nous avons exposée dans notre deuxième séquence — et qui repose sur des mots clé ou étiquettes, donne de bons résultats ;
- les notes manuscrites sur fiches sont généralement stockées dans un meuble dont la structure matérialise un index — comme l'armoire de Placcius et Leibniz — ;
- mais nous voulons ici aller plus loin, dans le cadre restreint des « notes » numérisées, en discutant de l'indexation de fichiers multiples qu'ils soient au format « texte » où dans d'autres format comme les images `jpg` où les fichier `pdf` ;
- cela nous amménera à introduire les « moteurs de recherche de bureau » et à expliquer comment des `étiquettes` ou `mots-clés` peuvent être ajoutés à nos fichiers.
<a id="org2811460"></a>
## La citation de Leibniz
J'ai trouvé la citation introductive :
« Il me semble que l'apparat savant contemporain est comparable à un grand magasin qui contient une grande quantité de produits, stockés de façon totalement désordonnée, mélangée ; où les nombres ou lettres d'indexation manquent ; où les inventaires et livres de comptes pouvant aider à ordonner le contenu ont disparus.
Plus grande est la quantité d'objets amassés, plus petite est leur utilité. Ainsi, ne devrions nous pas seulement essayer de rassembler de nouveaux objets de toutes provenances, mais nous devrions aussi essayer d'ordonner ceux que nous avons déjà. »
sur le site <http://www.backwordsindexing.com/index.html>, c'est donc une traduction de traduction. J'emploie ici le terme volontairement anachronique d'« [apparat savant](<https://fr.wikipedia.org/wiki/Apparat_savant>) » qui est un terme technique de l'édition désignant : citations, références et sources, notes en bas de pages, introduction, texte en langue originale (en parallèle avec la traduction), commentaire historique ou philologique, index fontium (les sources), index locorum (références avec renvoi à la page où le passage est cité ou mentionné, par ex. : Évangile selon Marc 1, 1 : p. 100), index nominum (les noms propres), index rerum (les thèmes), etc. La référence au « grand magasin » est, elle aussi anachronique !
Leibniz a, pendant une bonne partie de sa vie, « gagné celle-ci » comme [bibliothécaire](https://www.reseau-canope.fr/savoirscdi/societe-de-linformation/le-monde-du-livre-et-des-medias/histoire-du-livre-et-de-la-documentation/biographies/leibniz-le-bibliothecaire.html), ce qui explique en partie sont intérêt très poussé pour les questions de classifications, d'indexations, etc.
<a id="org56ad7e5"></a>
## Rechercher avec un éditeur de texte
La diapo correspondante rappelle juste au lecteur quelque chose qu'il sait déjà et qui est vue, par les gens qui passent des notes « papier » aux notes « numériques », comme le gros attrait du numérique.
Les gens de monde Unix/Linux connaissent aussi généralement le programme [grep](https://fr.wikipedia.org/wiki/Grep) qui permet de faire des recherches de mots et, plus généralement d'[expressions régulières](https://fr.wikipedia.org/wiki/Expression_r%C3%A9guli%C3%A8re), sur un ou *plusieurs* fichiers ; nous y reviendrons.
<a id="org5860004"></a>
## Recherche avec index construit « à la main » sur des cahiers de notes
Là encore, il s'agit juste d'un rappel pour les lecteurs assidus de ce cours ; à ce stade se sont des experts dans la méthode d'indexation de Locke.
<a id="orgfbae55d"></a>
## Recherche avec index « matérialisés »
Encore un rappel pour les lecteurs.
<a id="org648d1fa"></a>
## Vers les outils « sophistiqués » de l'informatique
- les techniques que nous venons de voir ou revoir ne fonctionnent que pour un seul « document » — recherche avec l'éditeur de texte, index d'un cahier — et/ou pour un seul type de document ;
- les outils informatiques dont nous disposons nous permettent d'aller plus loin dans l'indexation des fichiers numériques ;
- il est possible de rajouter des étiquettes ou mots-clés à des fichiers textes comme à des fichiers images (\`jpg\`, \`png\`) ou des fichiers « mixtes » (\`pdf\`) grâce aux métadonnées qu'ils contiennent ;
- les moteurs de recherche de bureau permettent d'indexer l'ensemble des fichiers textes d'une arborescence donnée mais aussi les métadonnées des autres fichiers.
<a id="org2570670"></a>
## Les moteurs de recherche de bureau
Les moteurs de recherche de bureau comme :
- [DocFetcher](http://docfetcher.sourceforge.net/fr/index.html) (Linux, MacOS, Windows) ;
- [Tracker](https://wiki.gnome.org/Projects/Tracker) (Linux) ;
- [Recoll](https://www.lesbonscomptes.com/recoll/index.html.fr) (Linux, MacOS, Windows) ;
- [Spotlight](https://fr.wikipedia.org/wiki/Spotlight_(moteur_de_recherche)) (MacOS) ;
permettent de rechercher le *contenu* des fichiers textes, des courriels, des fichiers générés par les `traitements de texte` — c'est-à-dire des fichiers qui contiennent essentiellement du texte, mais qui sont stockés dans un format type `doc`, `docx`, `odt`, etc qui ne sont pas des formats texte —, des fichiers `pdf` — quand ceux-ci ne sont pas des *images* de textes —, mais aussi des [métadonnées](https://en.wikipedia.org/wiki/Portable_Document_Format#Metadata) des fichiers `pdf`, etc.
Les moteurs de recherche de bureau « utilisent des techniques d'[indexation](https://fr.wikipedia.org/wiki/Indexation_automatique_de_documents) qui permettent de réduire considérablement les temps de recherche, par rapport aux fonctions de recherche intégrées par défaut aux systèmes d'exploitation. Au contraire de ces derniers, ils prennent aussi souvent en charge les [métadonnées](https://fr.wikipedia.org/wiki/M%C3%A9tadonn%C3%A9e), et sont capables de faire une [analyse syntaxique](https://fr.wikipedia.org/wiki/Analyse_syntaxique) des fichiers. » (Source : [Moteur de recherche de bureau](https://fr.wikipedia.org/wiki/Moteur_de_recherche_de_bureau) sur Wikipédia)
Comme exemple de « fonctions de recherche intégrées par défaut », on trouvera sur les systèmes Unix/Linux le programme [grep ](https://fr.wikipedia.org/wiki/Grep)avec lequel nous pouvons chercher les occurrences du mot « Galilée » dans le répertoire « RR<sub>MOOC</sub> » de notre cours sur GitHub (après l'avoir cloné) :
grep -r Galilée
PITCHME.md:## Galilée qui observe les lunes de Jupiter
PITCHME.md:Le 7 janvier 1610, Galilée fait une découverte capitale : il remarque trois « petites étoiles » à côté de Jupiter. Après quelques nuits d'observation, il découvre qu'il y en a une quatrième et qu'**elles accompagnent la planète**, c'est ce qu'il note sur son cahier d'observations. Ce sont les satellites visibles de Jupiter, qu'il nommera plus tard les étoiles Médicées ou astres médicéens – en l'honneur de ses protecteurs, la Famille des Médicis – et qui sont aujourd'hui appelés lunes galiléennes.
PITCHME.md:Ces observations amèneront Galilée à rejeter l'hypothèse géocentrique (la terre est le centre de l'Univers et tout tourne autour d'elle) en faveur du système copernicien héliocentrique. Cela l'amènera indirectement (je « fais court ») et bien plus tard, le 22 juin 1633, a être condamné par l'inquisition, ce qui lui vaudra de finir ses jours en résidence surveillée.
PITCHME.md:Remarquez l'avantage des « bouts de papiers classés » de Placcius et Leibniz sur le _codex_ de Galilée : les premiers peuvent être facilement réordonnées.
Notes_module1.org:- [[https://en.wikipedia.org/wiki/Galileo_Galilei][la page wikipedia sur Galilée]] contient de nombreux liens, certains vers ses cahiers de notes ;
Notes_module1.org:Comme exemple de « fonctions de recherche intégrées par défaut » on trouvera sur les systèmes Unix/Linux le programme [[https://fr.wikipedia.org/wiki/Grep][grep ]]avec lequel nous pouvons chercher les occurrences du mot « Galilée » dans le répertoire « RR_MOOC » de notre cours sur GitHub (après l'avoir cloné) :
Notes_module1.org:grep -r Galilée
Une version plus sophistiquée de `grep` est fournie par le programme [cgvg](http://uzix.org/cgvg.html).
<a id="org6714af0"></a>
## Pourquoi des étiquettes
Une requête basée sur un simple mot renvoie souvent un très grand nombre de propositions, même si la plupart des moteurs de recherche de bureau permettent de filtrer ces dernières. Une façon efficace de limiter leur nombre est d'inclure dans nos documents des étiquettes, c'est-à-dire des points d'ancrage labelisés, qui seront aisément indexés par le moteur de recherche de bureau et dont le label ne correspond à aucun mot ou locution du dictionnaire — nous effectuons ainsi une version simplifiée du travail de l'*indexeur*, la personne chargée de construire l'index d'un livre. Pour que l'étiquette garde un sens, il suffit d'encadrer un mot par une paire de signes de ponctuation comme « : », « ; » ou « ? ». Un label comme « :code: » sera facilement mémorisé et fera un parfait équivalent du mot-clé « code » utilisé dans l'exemple du cahier de note de la deuxième séquence de ce module — pour illustrer la méthode de Locke.
Il nous reste encore nous reste encore un détail technique à régler dans le cas de nos notes prises en format texte comme `Markdown`. En effet, nous ne souhaitons pas que nos étiquettes apparaissent dans les sorties `html`, `pdf` ou `docx` de nos notes. Un façon de procéder, pour les langages de balisage légers qui ne disposent pas d'étiquettes — par exemple, `Markdown` n'en dispose pas, alors que `org` en a — et de les inclure dans des commentaires. En `Markdown`, tout ce qui est encadré par `<!--` et `-->` est considéré comme un commentaire et ne figure pas dans les sorties `html` ou `pdf` des notes. Nous pouvons ainsi utiliser :
<!-- ;code; -->
à l'endroit de nos notes où nous souhaitons aller rapidement lorsque que nous cherchons une information relative à de la programmation (production de codes).
<a id="org987f9e0"></a>
## Les métadonnées
<a id="org86d9232"></a>
### Fichiers images
Nous savons à présent comment rajouter des étiquettes à un fichier au format texte, mais nous devons souvent aussi travailler avec des fichiers contenant des images ou des photos, comme les fichiers [JPEG](https://fr.wikipedia.org/wiki/JPEG) — les appareils photos numériques utilisent tous ce format —, [GIF](https://fr.wikipedia.org/wiki/Graphics_Interchange_Format) ou [PNG](https://fr.wikipedia.org/wiki/Portable_Network_Graphics). La question se pose alors, peut-on ajouter des étiquettes à nos fichiers images de sorte que nos moteurs de recherche de bureau les indexent ? La réponse et oui, grâce aux [métadonnées](https://fr.wikipedia.org/wiki/M%C3%A9tadonn%C3%A9e) que contiennent ces fichiers. Les métadonnées, dans ce cas, sont des données stockées dans le fichier mais qui ne sont pas montrées par le logiciel de rendu (en tout cas, pas montrées par défaut). Nous savons tous que ces métadonnées « existent » ; ce sont elles qui contiennent la date, la localisation GPS, le temps d'exposition, etc. de nos photos numériques. Dans les fichiers `JPEG`, elles sont stockées suivant l'[exchangeable image file format](https://fr.wikipedia.org/wiki/Exchangeable_image_file_format) (`EXIF`). La plupart des logiciels de manipulations d'images et de photos permettent d'accéder au contenu des métadonnées et de les modifier. L'exemple illustré dans le cours utilise une solution très simple en « ligne de commande », [ExifTool](http://owl.phy.queensu.ca/~phil/exiftool/) qui permet de visualiser et de modifier les métadonnées. D'autres logiciels comme [exiv2](http://www.exiv2.org/index.html) ou [ImageMagick](https://imagemagick.org/script/index.php) permettent de le faire (pour ne citer que des logiciels libres disponibles sur Linux, Windows et MacOS). Certains des éléments du format `EXIF` sont des chaînes de caractères, c'est-à-dire du texte, que nous somme libres d'utiliser comme nous le souhaitons ; nous pouvons dès lors les utiliser pour rajouter nos étiquettes. Nous illustrons dans le cours comment le faire avec `ExifTool`, mais nous aurions aussi pu le faire avec le programme [mogrify](https://www.imagemagick.org/script/command-line-options.php#comment) d'ImageMagick. Tous les moteurs de recherche de bureau que nous avons mentionné vont « aller regarder » les métadonnées des fichier `JPEG` lors de la phase d'indexation et nous permettront ainsi d'exploiter les étiquettes que nous y aurons insérées.
`EXIF` n'est pas le seul format de métadonnées existant ; un format plus récent est l'[Extensible Metadata Platform ](https://fr.wikipedia.org/wiki/Extensible_Metadata_Platform)(`XMP`), disponible pour un plus grand nombre de formats de fichiers — il n'est pour l'instant pas lu sur les fichiers `JPEG` par `DocFetcher`, c'est pourquoi nous avons mis en avant le format `EXIF`, mais cela devrait évoluer assez vite ; les autres moteurs comme `Tracker` et `Recoll` le lisent.
<a id="orgca6fceb"></a>
### Fichiers `PDF`
En plus des fichiers images, nous sommes tous très fréquemment amenés à travailler avec les fichiers « composites » — contenant textes, images, et plus — que sont les fichiers [PDF](https://fr.wikipedia.org/wiki/Portable_Document_Format). Ces fichiers contiennent eux aussi des métadonnées ; c'est d'ailleurs pour eux qu'Adobe a initialement introduit le format `XMP` que nous venons de discuter. Ces métadonnées peuvent être lues et modifiées, en particulier l'élément `Keywords` (mot-clé) qui peut contenir des chaînes de caractères de longueur arbitraires et qui est parfait pour accueillir nos étiquettes. Le programme `ExifTool`, permet de modifier les métadonnées des fichiers `PDF`. Les moteurs de recherche de bureau que nous avons mentionnés, vont tous aller lire les métadonnées des fichiers `PDF` lors de la phase d'indexation.
<a id="org87a2419"></a>
### Fichiers audios
Les formats audio comme le [mp3](https://fr.wikipedia.org/wiki/MPEG-1/2_Audio_Layer_III) ou le [ogg](https://fr.wikipedia.org/wiki/Ogg) contiennent eux aussi des métadonnées, où sont stockés les titres, noms des interprètes, etc ; ces métadonnées peuvent être modifiées et sont lues par les moteurs de recherche de bureau lors de la phase d'indexation.
module1/slides/misc/Notes_module1.md deleted 100644 → 0
View file @ 8986dad7
# Table des matières
1. [Introduction au module](#orge43986e)
1. [Le « cahier de notes »](#org730212d)
1. [Exemples concrets de « cahier de notes »](#org2a90588)
2. [Notes et références sur la séquence 1 : « Nous utilisons tous des cahiers de notes »](#orgf5eeda3)
1. [Manuscrits annotés](#orgc71b34a)
2. [Armoires à notes de Placcius et Leibniz](#org60d83a8)
3. [La préface de « L'île des pingouins » d'Anatole France](#org15f16da)
4. [Les livres de bord](#org2019f41)
5. [Un absent : le cahier de laboratoire classique](#org16eb5e8)
3. [Notes et références sur la séquence 2 : « Un aperçu historique de la prise de notes »](#org1ae2571)
1. [Références générales](#orge284492)
2. [Sur les tablettes de cires](#org8dd9b50)
3. [Sur le passage du rouleau (*volumen*) au codex](#org172e431)
4. [Sur Eusèbe de Césarée](#org0f408c9)
5. [Parallèle chinois](#org898d2c5)
6. [Retour sur l'armoire à notes](#org23f1477)
7. [L'index et John Locke](#orge852c7e)
4. [Notes et références sur la séquence 3 : « Du fichier texte au langage de balisage léger »](#org30c5f99)
1. [Fichier texte et éditeur de texte](#orgf02472f)
2. [Le cas du fichier `PDF` ouvert avec un éditeur de texte](#org4c92ae2)
3. [Sur l'UTF-8](#org1305f4c)
5. [Notes et références sur la séquence 5 : « Les étiquettes et les logiciels d'indexation pour s'y retrouver »](#orgaba3aca)
1. [La structure de la séquence](#orgfcff6c0)
2. [La citation de Leibniz](#org32aaaed)
3. [Rechercher avec un éditeur de texte](#orgdbf92e1)
4. [Recherche avec index construit « à la main » sur des cahiers de notes](#orgab1d546)
5. [Recherche avec index « matérialisés »](#orgebb0a49)
6. [Vers les outils « sophistiqués » de l'informatique](#orgddef543)
7. [Les moteurs de recherche de bureau](#orgaf4f7ba)
8. [Pourquoi des étiquettes](#org06edb53)
9. [Les métadonnées](#orgd05cefb)
1. [Fichiers images](#org35c9a2a)
2. [Fichiers `PDF`](#org1dca817)
3. [Fichiers audios](#orgea7f02d)
<a id="orge43986e"></a>
# Introduction au module
La mise en œuvre de la « recherche reproductible ou réplicable » requiert en plus des codes et des données une description de la façon dont les premiers ont été appliqués aux secondes. Cette description devrait contenir une **discussion du choix** des paramètres / arguments des codes lorsque ceux-ci ne sont pas choisis de façon automatique / algorithmique. Des considérations du même ordre doivent d'ailleurs s'appliquer à la conception (choix des algorithmes) et à la réalisation (choix du langage, des librairies, etc.) des codes comme à la conception et à la réalisation de la collecte de données, c'est-à-dire des expériences, des enquêtes, etc.
Le praticien de la recherche reproductible se trouve ainsi confronté à un problème somme toute classique : garder une trace, documenter ce qui est fait. L'épitête « classique » se justifie dès lors que le lecteur réalise qu'il a lui aussi souvent été confronté à ce problème même si sous des formes légérement différentes. Ainsi, bon nombre d'entre nous doit effectuer un travail bibliographique plus ou moins fréquemment, ce qui génère des « notes » pouvant prendre diverse formes sur un ou plusieurs supports. Mais ce travail de prise de notes, ce « traçage », ne s'arrête, le plus souvent, pas là. Prenons le cas de l'algorithme à mettre en œuvre ; après une étude bibliographique en ayant identifié quelques-uns *a priori* applicable à la situation rencontrée, il nous faudra soit les coder nous-mêmes, soit les trouver déjà codés sur un dépôt type [github](https://github.com/) ou [gitlab](https://about.gitlab.com/) ; quelque soit la solution adoptée, il nous faudra la documenter &#x2013; /en expliquer les raisons/, ce qui peut impliquer une courte étude comparative &#x2013; avec des références adéquates ce qui générera de nouvelles notes sur support papier ou numérique. En poursuivant cette logique, on voit vite que la quasi totalité de notre activité peut (ou devrait) s'accompagner d'une prise de notes. Voilà pourquoi notre premier module traitera d'une question qui ne se limite pas, loin s'en faut, à la recherche reproductible, celle du « cahier de notes ». Ce module commencera donc en vous disant quelque chose que vous savez déjà (!) : « nous devons tous prendre des notes. »
Si nous devons tous prendre des notes, nos prédécesseurs ont du le faire aussi. Cette constatation élémentaire faite, nous éviterons de croire que nous sommes les premiers à avoir à faire face un déluge d'informations. Nous en profiterons pour apprendre comment nos brillants ancêtres s'y sont pris. En nous inspirant de nos connaissances des « anciennes » techniques, nous verrons ensuite comment mettre à profit les outils fournis par l'informatique.
Les fichiers texte et les langages de balisage léger vont nous permettre de structurer nos notes et de les « recycler » facilement (dans des articles, des pages web, etc.). La gestion de version nous évitera de tout perdre tout en gardant trace de nos corrections et modifications successives. Enfin, reprendre une activité de zéro parce que retrouver la bonne information dans la jungle de nos notes prendrait plus de temps ne sera plus qu'un souvenir avec la construction d'index.
<a id="org730212d"></a>
## Le « cahier de notes »
Le « cahier de notes » doit être considéré ici « au sens large » ; c'est-à-dire que, suivant le contexte, il sera plus proprement appelé « cahier de terrain », « cahier d'observations », « journal » ou « cahier de laboratoire ». Ce qui nous intéresse ici est la notion de supports (papiers ou numériques) dans lesquels des informations sont stockées au fil du temps &#x2013; contrairement au cas d'un mémoire ou d'un article où c'est la logique de l'argumentation qui structure le contenu &#x2013; ; ces informations sont de plus de nature souvent hétérogène et leurs supports, lorsqu'ils sont multiples, aussi (par exemple, un cahier de notes associé à des fichiers textes).
<a id="org2a90588"></a>
### Exemples concrets de « cahier de notes »
- [Les cahiers de Léonard de Vinci](http://unesdoc.unesco.org/images/0007/000748/074877fo.pdf) et la page Wikipédia sur [Le Codex Leicester](https://fr.wikipedia.org/wiki/Codex_Leicester) ;
- [la page wikipedia sur Galilée](https://en.wikipedia.org/wiki/Galileo_Galilei) contient de nombreux liens, certains vers ses cahiers de notes ;
- [Les « registres de laboratoire » de Pasteur](http://gallica.bnf.fr/Search?ArianeWireIndex=index&p=1&lang=EN&f_typedoc=manuscrits&q=Louis+Pasteur+registres) sont disponibles sur Gallica ;
- [Les dossiers préparatoires de Zola pour les Rougon-Macquart](http://gallica.bnf.fr/ark:/12148/btv1b90797770/f1.image.r=Emile%20Zola) sont aussi disponibles sur Gallica ;
- [Le journal de bord de James Cook](https://ebooks.adelaide.edu.au/c/cook/james/c77j/index.html) lors de son premier voyage sont consultables &#x2013; [un autre exemple](http://southseas.nla.gov.au/journals/hv01/title.html) plus complet est aussi disponible &#x2013;, la [page Wikipedia](https://en.wikipedia.org/wiki/James_Cook) contient un grand nombre de liens ;
- L'essentiel des [cahiers de notes de Charles Darwin](http://darwin-online.org.uk/) est consultable en ligne ;
- [Les fiches de Carl von Linnée](http://linnean-online.org/61332/#/0) sont consultables en ligne ;
- [Les cahiers de laboratoire de Linus Pauling](http://scarc.library.oregonstate.edu/coll/pauling/rnb/index.html) sont disponibles dans leur intégralité ;
- L'histoire de la [mesure du méridien](https://fr.wikipedia.org/wiki/Figure_de_la_Terre_et_m%C3%A9ridienne_de_Delambre_et_M%C3%A9chain#M%C3%A9ridienne_de_Delambre_et_M%C3%A9chain_et_progr%C3%A8s_scientifiques_%C3%A0_la_m%C3%AAme_%C3%A9poque) de Dunkerke à Barcelone par Delambre et Méchain est remarquablement contée dans le livre de Ken Alder, « Mesurer le monde - 1792-1799 : l'incroyable histoire de l'invention du mètre » (en poche chez Flammarion) ; les cahiers de notes y jouent un rôle tout à fait primordial.
<a id="orgf5eeda3"></a>
# Notes et références sur la séquence 1 : « Nous utilisons tous des cahiers de notes »
<a id="orgc71b34a"></a>
## Manuscrits annotés
En guise d'entrée dans l'univers des manuscrits annotés, je fais suivre une petite sélection de passages du premier chapitre de « LA PAGE. DE L'ANTIQUITÉ À L'ÈRE DU NUMÉRIQUE » d'Anthony Grafton (Hazan, 2012) :
Par le mouvement même de sa plume sur la page, il est clair que
Casaubon maîtrise tout ce qu'il lit. Constamment, il souligne des
mots et des expressions, il note en marge des mots clés et des résumés
montrant qu'il a lu attentivement, même quand, précise-t-il dans son
journal intime, il étudie en une journée quarante à cinquante pages
in-folio de grec émaillées de nombreuses abréviations. Les passages
plus importants donnent lieu en marge à des commentaires plus
longs. Sur les pages de titre, Casaubon porte très souvent — un peu
comme Montaigne — un jugement global sur la valeur de l'ouvrage.
Par ailleurs, il note ses réflexions dans des carnets, ou prend
des notes sur des textes qu'il ne peut pas acheter. Tels qu'ils sont
réunis dans sa bibliothèque, ses livres représentent une vie entière de
lecture que l'on peut reconstituer au fil des pages.
Pages 32 et 33, à propos d'[Isaac Casaubon](https://fr.wikipedia.org/wiki/Isaac_Casaubon) (1559-1614).
Pourtant, Harvey a laissé beaucoup plus que cela, et notamment
des traces des ses lectures sous forme de plus d'une centaine de livres
couverts d'annotations magnifiquement écrites de sa belle écriture
italique — en plus des cahiers dans lesquels il notait des extraits.
Manifestement, Harvey considérait la lecture comme sa profession,
et il en a fait aussi un art. Décennie après décennie, il couche ses
pensées sur l'histoire dans une édition in-folio de 1555 de l'Histoire
romaine de Tite-Live. Ses notes, en latin pour la plupart, parcourent
les marges, se répandent entre les chapitres et remplissent
des feuilles volantes, prenant un aspect particulièrement érudit et
assez rébarbatif.
Pages 35 et 36, à propos de [Gabriel Harvey](https://en.wikipedia.org/wiki/Gabriel_Harvey) (1545-1630).
... Mais dans l'exemplaire de travail qui subsiste du
texte, l'édition de base de 1549, il [Casaubon] introduit tant d'annotations
précises que les catalogueurs de la Bibliothèque bodléienne, qui n'étaient
pas rompus à la rhétorique, ont classé ce livre imprimé parmi les manuscrits.
Page 40.
<a id="org60d83a8"></a>
## Armoires à notes de Placcius et Leibniz
J'ai trouvé cet exemple dans les travaux d'[Ann Blair](https://projects.iq.harvard.edu/ablair) comme « [The Rise of Note-Taking in Early Modern Europe](https://dash.harvard.edu/handle/1/4774908) » et son livre « [TOO MUCH TO KNOW. Managing Scholarly Information before the Modern Age](https://yalebooks.yale.edu/book/9780300165395/too-much-know) », publié chez *Yale University Press* en 2011.
<a id="org15f16da"></a>
## La préface de « L'île des pingouins » d'Anatole France
Étant très loin de connaître Anatole France sur le bout des doigts, j'ai trouvé la référence citée dans le remarquable article de Keith Thomas publié par la *London Review of Books*, [le 10 juin 2010](https://www.lrb.co.uk/v32/n11/keith-thomas/diary). Cet article (en anglais) décrit et discute le travail concret de prise de notes par un historien, il est de plus très bien écrit et plein d'anecdotes.
<a id="org2019f41"></a>
## Les livres de bord
Je remercie Joël Caselli de m'avoir aidé à interpréter le contenu du livre de bord d'Éric Tabarly.
Le projet européen de reconstruction des climats des océans atlantique et indien (et non pacifique comme je le dis dans le cours !) : [*Climatological Database for the World's Oceans 1750-1850*](http://webs.ucm.es/info/cliwoc/) ; dispose d'un site internet très intéressant (mais en anglais).
On trouvera des citations abondantes (et effrayantes) de livres de bord de navires négriers dans le livre de Marcus Rediker « À bord du négrier : Une histoire atlantique de la traite » (disponible en édition de poche).
<a id="org16eb5e8"></a>
## Un absent : le cahier de laboratoire classique
Je traduis ici la section 6.2 *Notebooks and Records* du remarquable livre de E. Bright Wilson *An Introduction to Scientific Research* réimprimé par Dover.
Il est difficile de concevoir un cahier de laboratoire parfait et il est malheureusement rare d'en trouver un qui soit même à peu près satisfaisant ; la conservation d'une trace écrite du travail effectué est néanmoins une source majeure d'efficacité. Il y aura forcément des gens opposés à un ensemble de règles fixes, mais cela sera probablement plus rare pour le rituel de garder un cahier que sur d'autres sujets. Par conséquent, un ensemble de règles qui sont généralement considérées comme satisfaisantes, voire même essentielles, seront quelque peu dogmatiquement énoncées.
De grandes découvertes ont été retardées en raison d'une négligente tenue des traces écrites. L'astronome Le Monnier est ainsi supposé avoir observé la planète Uranus à plusieurs reprises &#x2013; avant que son identification comme planète ait été annoncée par Herschel &#x2013;, mais a décidé qu'elle était une étoile fixe. Cela s'explique probablement en partie par le fait qu'il a écrit ses mesures sur des morceaux de papier, y compris un sac en papier contenant à l'origine de la poudre pour cheveux !
Les cahiers de laboratoire doivent être solidement reliés, d'une taille approximative de 20 x 25 cm, avec des pages numérotées. Les feuilles séparées sont trop facilement perdues pour être satisfaisantes, d'autant plus qu'un cahier de laboratoire subit souvent un traitement un peu rude avec peut-être des projections occasionnelles d'acide [c'est un physico-chimiste qui écrit]. Le cas de mesures répétées constitue une exception où une ébauche spéciale imprimée est souvent utile si un bon système est établi pour collecter et relier les feuilles séparées. Les pages avec des lignes sont généralement utilisées, mais il s'agit d'une question de goût personnel, et certaines préfèrent des pages blanches ou à carreaux. Un tampon en caoutchouc peut être utilisé pour fournir des en-têtes pour les entrées les plus communes.
Les données doivent être entrées directement dans le cahier au moment de l'observation. Il est intolérable d'utiliser sa mémoire ou des fragments de papier pour l'enregistrement primaire, du fait de l'inévitabilité des erreurs et des pertes. Il devrait donc y avoir une bonne place pour le cahier à coté du poste de travail, et l'expérimentateur ne devrait jamais être sans son cahier lorsqu'il est en action.
Les données doivent être enregistrées à l'encre, de préférence une encre permanente, un buvard peut être pratique. Sinon, la trace écrite est trop éphémère. Les cahiers sont soumis à une utilisation intensive et les écritures au crayons se détériorent trop rapidement. Lorsque le cahier peut être utilisé comme preuve pour un brevet, l'usage de l'encre s'impose.
Des graphiques approximatifs et qualitatifs peuvent être dessinés directement, mais les graphiques précis sont généralement préparés avec le papier graphique du type le plus approprié [pensez au papier millimétré]. Ils sont ensuite soigneusement collés dans le cahier, une page vierge étant découpée afin de compenser l'épaisseur ajoutée.
Les cahiers doivent porter le nom de l'utilisateur et les dates couvertes. [&#x2026;]. Les huit ou dix premières pages devraient être réservées pour une table des matières. Il s'agit de lignes ajoutées chronologiquement pour chaque série d'expériences similaires, ainsi que la référence de la page. La table des matières est extrêmement utile pour trouver des éléments plus tard et est très simple à suivre. Un index au dos du cahier est avantageux mais pas indispensable.
Chaque élément devrait être datée et, si plusieurs personnes utilisent un cahier (généralement pas recommandé), paraphé. Le contenu ne devrait pas inscrit de façon trop dense sur les pages ; le papier est bon marché par rapport aux autres dépenses de recherche.
La principale difficulté est de décider ce qu'il faut écrire dans le cahier. Évidemment, on entre les résultats numériques et les valeurs des variables indépendantes telles que la température, la composition ou la pression qui sont directement pertinentes. Il est également nécessaire d'avoir un système d'entrées ou de références afin que, plus tard, il soit possible de dire quel appareil a été utilisé et dans quelles circonstances. Une description assez complète de l'appareil devrait être conservée. Ensuite, lorsque des modifications sont apportées à l'appareil, elles doivent être décrites immédiatement dans le cahier. Il devrait également être possible de retracer la source des courbes d'étalonnage, des corrections, etc., qui étaient appropriées aux données d'un jour donné. Il est utile que les exigences relatives à l'écriture d'un article, d'une thèse ou d'un livre soient gardées à l'esprit. Une telle tâche, une fois effectuée, entraîne généralement la résolution solennelle de garder un cahier plus détaillé dans le futur. Essayer de comprendre le cahier de notes de quelqu'un d'autre constitue aussi un exercice hautement salutaire. Toutes les références aux appareils, aux lieux, aux horaires, aux livres, aux articles, aux graphiques et aux personnes devraient être suffisamment explicites pour être compréhensibles des années plus tard. **Il devrait être possible de prendre chaque article scientifique et de montrer exactement où chaque figure, description ou déclaration est justifiée par des observations originales dans le cahier de laboratoire, et exactement pourquoi les nombres final et original diffèrent, si tel est le cas**.
Un énoncé du but de chaque expérience et un résumé des conclusions obtenues rendent le cahier beaucoup plus utile.
Les croquis, dessins et diagrammes sont essentiels. Comme tant d'observations sont visuelles, *il est important de noter ce qui est réellement vu, y compris des éléments qui ne sont pas entièrement compris lors de leur observation*.
Les expériences mauvaises ou non prometteuses, même celles considérées comme des échecs, devraient être entièrement enregistrées. Elles représentent un effort qui ne doit pas être gaspillé, car souvent quelque chose peut être récupéré, même si ce n'est qu'une connaissance de ce qu'il ne faut pas faire.
Les données doivent toujours être entrées dans leur forme la plus primaire, et non après un calcul ou une transformation. Si c'est le rapport de deux observations qui est intéressant, mais si les deux nombres sont effectivement observés, les deux nombres doivent être enregistrés. Si le poids précis d'un objet est important, les poids d'équilibrage individuels utilisés et leur identification devraient être inclus, c'est-à-dire le numéro de série de leur boîte. Dans le cas contraire, il devient impossible d'appliquer ultérieurement des corrections d'étalonnage ou de modifier les corrections si de nouvelles valeurs apparaissent. Naturellement, ce détail n'est pas nécessaire si seulement un poids approximatif est impliqué. La forme tabulaire est la meilleure pour les données numériques. Les unités doivent être notées.
Lorsque des brevets sont impliquées, il peut être souhaitable d'authentifier les pages des cahiers à intervalles réguliers. Le témoin devrait être quelqu'un qui comprend le contenu mais qui n'est pas impliqué dans la recherche. Un contenu ajouté ultérieurement à une page devrait l'être dans une encre de couleur différente, et toutes les modifications devraient être paraphées, authentifiées et datées si elles sont susceptibles d'être importantes. Les entreprises industrielles font ainsi généralement respecter leurs propres règles en matière de cahiers de laboratoire.
**Numéros d'identification**. Il est stupide de consacrer du temps et de l'argent à des enregistrements de différents types [&#x2026;] si ceux-ci sont ensuite perdus ou mélangés. Tout enregistrements qui ne peut être inclut directement dans le cahier de notes devraient porter une identification complète indélébile. Un système simple qui a fait ses preuves consiste à écrire à l'encre sur chaque enregistrement un symbole identifiant le cahier, puis le numéro de page sur lequel les données auxiliaires sont enregistrées. Si plus d'un enregistrement sont mentionnés sur une page du cahier, des lettres ou des chiffres supplémentaires peuvent être ajoutés. Ainsi, EBW II 85c identifie le troisième enregistrement discuté à la page 85 du deuxième cahier EBW. C'est mieux qu'un numéro de série qui ne dit pas, sans clé supplémentaire, où chercher la description le concernant dans le cahier.
Un bon système de classement est indispensable pour tous les films, les photographies, les schémas, les graphiques, les diagrammes de circuit, les dessins, les plans, etc. Il est plus difficile de concevoir des méthodes de dépôt satisfaisantes pour des matériaux très petits ou très grands. Les premiers sont facilement perdus et les dernier très volumineux. [&#x2026;]
Il est important d'archiver les dessins et les plans à partir desquels les appareils utilisés ont été construits, même si ces dessins sont grossiers. Ils doivent être datés, paraphés et étiquetés ; en fait, tout morceau de papier contenant une information utile devrait être marqué de la sorte. Lorsqu'un équipement électronique ou autre est fabriqué, son diagramme doit être soigneusement préparé et entièrement étiqueté avec toutes les constantes. L'appareil doit porter un numéro de série qui apparaît également sur ce diagramme. Lorsque des modifications sont apportées, celles-ci doivent être indiquées sur le schéma et datées ou un diagramme révisé et daté doit être préparé. L'ancien ne doit pas être obscurci ou jeté, car il peut être nécessaire pour expliquer des données antérieures, considérées ultérieurement comme étranges. [&#x2026;]
Le but de toute cette pratique de prise de notes est de préserver la valeur [le temps et les moyens humains et matériels investis dans la recherche]. Elle devrait être soigneusement conçus pour s'adapter aux conditions de chaque laboratoire et devraient être adéquate mais pas trop élaborés. **Si l'on exige trop de la nature humaine, le système ne fonctionnera pas**.
<a id="org1ae2571"></a>
# Notes et références sur la séquence 2 : « Un aperçu historique de la prise de notes »
<a id="orge284492"></a>
## Références générales
En plus des deux livres déjà cités :
- « LA PAGE. DE L'ANTIQUITÉ À L'ÈRE DU NUMÉRIQUE » d'Anthony Grafton (Hazan, 2012) ;
- « [TOO MUCH TO KNOW. Managing Scholarly Information before the Modern Age](https://yalebooks.yale.edu/book/9780300165395/too-much-know) », d'Ann Blair publié chez *Yale University Press* en 2011 ;
j'ai utilisé :
- « L'histoire du livre » de Frédéric Barbier ;
- le remarquable site de Jacques Poitou, [langages écritures typographies](http://j.poitou.free.fr/pro/index.html) ;
- le site [l'aventure des écritures](http://classes.bnf.fr/ecritures/) de la BNF ;
- le catalogue de l'exposition de la BNF « Tous les savoirs du monde : Encyclopédies et bibliothèques de Sumer au XXIème siècle » ;
- « [Du papyrus à l'hypertexte](http://litmedmod.ca/sites/default/files/pdf/vandendorpe-papyrusenligne_lr.pdf) » de Christian Vandendorpe (La Découverte, 1999).
<a id="org8dd9b50"></a>
## Sur les tablettes de cires
Voir le site de Jacques Poitou (d'où les illustrations sont empruntées) et le livre de Frédéric Barbier, « L'histoire du livre ».
<a id="org172e431"></a>
## Sur le passage du rouleau (*volumen*) au codex
Voir le livre de Frédéric Barbier, celui d'Anthony Grafton.
Le *volumen* est un livre à base de feuilles de papyrus collées les unes aux autres et qui s'enroule sur lui-même. Il a été créé en Égypte vers 3000 av. J.-C. Le texte est rédigé en colonnes parallèles assez étroites. C'est le support du texte par excellence durant les trente siècles précédant notre ère, d'abord en Égypte, puis dans tout le monde méditerranéen.
Comme l'explique Frédéric Barbier : « La forme du *volumen* impose une pratique de lecture complexe : il faut dérouler (*explicare*) et enrouler en même temps, ce qui interdit par exemple, de travailler simultanément sur plusieurs rouleaux (un texte et son commentaire) ou de prendre des notes, impose une lecture suivie et empêche la simple consultation. »
Le *volumen* n'est clairement pas adapté à une lecture « nomade » ; imagine-t-on Ulysse partant pour son Odyssée avec les 24 *volumen* de l'Iliade ?
Le *volumen* est à l'origine du terme « volume » dans un « livre en plusieurs volumes » comme dans la désignation du concept géométrique.
Le passage au codex repose sur deux innovations :
- la collection des tablettes de cires en « groupes reliés » ;
- la généralisation du parchemin (peau, généralement, de mouton spécialement préparée) au détriment du papyrus. Cette généralisation résulte une lutte pour l'hégémonie culturelle entre deux descendants de généraux d'Alexandre le Grand, en effet d'après Pline l'ancien : [Ptolémé Épiphane](https://fr.wikipedia.org/wiki/Ptol%C3%A9m%C3%A9e_V) d'Alexandrie cherchait à empêcher [Eumène II](https://fr.wikipedia.org/wiki/Eum%C3%A8ne_II) d'établir une bibliothèque à Pergame (au 2e siècle avant J.-C.) et avait interdit l'exportation du papyrus (produit exclusivement en Égypte), ce qui incita Eumène à chercher un substitut qui devint le parchemin.
Le remplacement du rouleau par le codex aura des conséquences majeures sur l'organisation du livre ainsi que sur la façon de lire et il permettra le développement ultérieur de l'imprimerie.
La principale révolution introduite par le codex est la notion de page. Grâce à elle, le lecteur peut accéder de manière directe à un chapitre ou à un passage du texte, alors que le rouleau impose une lecture continue. **Les mots ne sont de plus pas séparés par des espaces**. Comme l'écrit Collette Sirat : « Il faudra vingt siècles pour qu’on se rende compte que l’importance primordiale du codex pour notre civilisation a été de permettre la lecture sélective et non pas continue, contribuant ainsi à l’élaboration de structures mentales où le texte est dissocié de la parole et de son rythme. »
Au fil des siècles, le codex — qu'on désigne le plus souvent comme un manuscrit — va évoluer et se donner peu à peu les attributs du livre moderne : séparation entre les mots (VIIe siècle), début de ponctuation (VIIIe siècle), table des matières, titre courant, marque de paragraphe (XIe siècle), pagination, index (XIIIe siècle), etc.
Un point intéressant : le contenu de la Thora est « fixé » avant l'apparition du codex et, aujourd'hui encore, la Thora est écrite sur des *volumen* (dans les synagogues au moins). La religion chrétienne se développe en même temps que le codex, adopte ce support et le répand ; elle ne donnera jamais au *volumen* un statut « supérieur », pas plus que ne le fera la religion musulmane.
<a id="org0f408c9"></a>
## Sur Eusèbe de Césarée
Pour en savoir plus sur [Eusèbe de Césarée](https://fr.wikipedia.org/wiki/Eus%C3%A8be_de_C%C3%A9sar%C3%A9e), consultez le passionnant deuxième chapitre du livre d'Anthony Grafton.
<a id="org898d2c5"></a>
## Parallèle chinois
Comme je le dis, mon inculture fait que je ne rends pas justice aux contributions chinoises, musulmanes, précolombienne, etc. J'essaierai de combler cette énorme lacune pour les seconde version du CLOM&#x2026;
Ce que je dis sur le passage du volumen au codex accompagné d'un développement des « outils de navigation » (index, table des matières, etc) en Chine lors du développement de leishus vient du bouquin d'Ann Blair (p. 31) qui cite un article de Susan Cherniack, « Book Culture and Textual Transmission in Sung China », *Harvard Journal of Asiatic Studies* Vol. 54, No. 1 (Jun., 1994), pp. 5-125.
<a id="org23f1477"></a>
## Retour sur l'armoire à notes
Nous revenons sur le « bout de papier » ou la fiche comme support de note. L'inconvénient est que le bout de papier ou la fiche se perdent facilement et ne servent à rien s'ils ne sont pas **classés** en plus d'être rangés. Problème résolu par l'armoire de Placcius. D'une certaine façon, sa conception fait qu'on accède à son contenu par l'index.
L'avantage est que les notes peuvent être réorganisées si elles contiennent des information sur plusieurs sujets. Elle peuvent aussi être directement collées dans un livre lors de la composition d'un florilège ou d'un ouvrage de synthèse.
Ce dernier procédé était très couramment employé par les humanistes et les érudit de la renaissance et du début de la période moderne. [Conrad Gessner](https://fr.wikipedia.org/wiki/Conrad_Gessner) (1516-1565) était un champion de cette technique ; il obtenait même parfois ses fiches en découpant les pages des livres. Encore une fois, ne faites pas cela avec les livres de bibliothèques !
<a id="orge852c7e"></a>
## L'index et John Locke
Sur l'origine de l'index, on pourra lire l'article de Jean Berger : [Indexation, Memoire, pouvoir et representations au seuil du XIIe siecle : La redecouverte des feuillets de tables du Liber De Honoribus, premier cartulaire de la collegiale Saint-Julien de Brioude](https://www.theindexer.org/files/25-2-berger.pdf), *The Indexer*.
La méthode de John Lock est expliquée dans l'article *Indexing commonplace books: John Locke’s method* d'Alan Walker, [The Indexer](https://www.theindexer.org/issues/query.php?vol=22&iss=3), vol. 22, p. 114-118, 2001.
Sur [John Locke](https://fr.wikipedia.org/wiki/John_Locke) (1632-1704) « papa du libéralisme » et actionnaire de la *Royal African Company* principale compagnie négrière britannique, voir l'article [Wikipedia](https://en.wikipedia.org/wiki/John_Locke#Constitution_of_Carolina) (en anglais) et le livre « Contre-histoire du libéralisme » de Domenico Losurdo (La Découverte / Poche, 2014, p. 34-36).
<a id="org30c5f99"></a>
# Notes et références sur la séquence 3 : « Du fichier texte au langage de balisage léger »
<a id="orgf02472f"></a>
## Fichier texte et éditeur de texte
Une définition plus technique (et moins circulaire !) du fichier texte se trouve sur [la page wikipédia](https://fr.wikipedia.org/wiki/Fichier_texte) consacrée au sujet. Pour plus de détails sur les éditeurs de texte, voir aussi la [page wikipédia correspondante](https://fr.wikipedia.org/wiki/%C3%89diteur_de_texte).
Un logiciel de « [traitement de texte](https://fr.wikipedia.org/wiki/Traitement_de_texte) » est plus sophistiqué qu'un simple éditeur de texte ; il permet de faire plus, ce qui sous entend qu'il peut aussi ouvrir et manipuler des fichiers textes.
\*Attention\* : le format « natif » des traitements de texte est rarement un format texte. Les fichiers `doc` et `docx` de `Word` et `odt` de `LibreOffice` *ne sont pas des fichiers textes*.
<a id="org4c92ae2"></a>
## Le cas du fichier `PDF` ouvert avec un éditeur de texte
Dans le cours filmé, j'utilise l'exemple du [PDF](https://en.wikipedia.org/wiki/Portable_Document_Format) — je donne l'adresse de la page wikipedia en anglais, bien plus complète que celle en français — ouvert avec un éditeur de texte pour montrer que le fichier ne peut pas être visualisé avec un tel logiciel, il faut un logiciel de rendu dédié comme `Adobe Reader`, `Evince`, `MuPDF`, `Aperçu`,&#x2026; Vous remarquez néanmoins que le début du fichier contient du texte (la première ligne nous apprend que le fichier utilise la version 1.3 du format `PDF`). Cette partie au format texte du fichier contient les méta-données — qui ne sont pas montrées, en tout cas pas directement, par les logiciels de rendu. Ces méta-données sont (en partie) au format [XMP](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) (*Extensible Metadata Platform*), nous y reviendrons dans la cinquème séquence.
<a id="org1305f4c"></a>
## Sur l'UTF-8
Une table des symboles UTF-8, avec leur code se trouve à l'adresse : <http://www.utf8-chartable.de/>. C'est pratique pour insérer un symbole pas très courant comme la lettre « TLO » : Ꮰ de la langue cherokee, ou le symbole mathématique ∀, « pour tout ».
Pour ceux qui doivent souvent utiliser des lettres grecs (par exemple pour écrire des équations), il est possible sous Linux de (re)définir des combinaisons de touches pour générer directement les dites lettres. Ces combinaisons sont définies dans le fichier `.XCompose`, le début de mon fichier contient :
# On charge la base de donnée de Compose la plus complète en UTF-8
include "/usr/share/X11/locale/en_US.UTF-8/Compose"
# espace insécable fine
<Multi_key> <Multi_key> <Space> : " " U202F
# Lettres greques
<Multi_key> <space> <a> : "α" Greek_alpha
<Multi_key> <space> <A> : "Α" Greek_ALPHA
<Multi_key> <space> <b> : "β" Greek_beta
<Multi_key> <space> <B> : "Β" Greek_BETA
<Multi_key> <space> <g> : "γ" Greek_gamma
<Multi_key> <space> <G> : "Γ" Greek_GAMMA
<Multi_key> <space> <d> : "δ" Greek_delta
<Multi_key> <space> <D> : "Δ" Greek_DELTA
<Multi_key> <space> <e> : "ε" Greek_epsilon
<Multi_key> <space> <E> : "Ε" Greek_EPSILON
<Multi_key> <space> <z> : "ζ" Greek_zeta
<Multi_key> <space> <Z> : "Ζ" Greek_ZETA
<Multi_key> <space> <h> : "η" Greek_eta
J'ai en plus redéfini la « <Multi\_key> » pour qu'elle corresponde à la touche « impression d'écran » de mon clavier. Pour apprendre à redéfinir des touches, consultez : <https://wiki.archlinux.org/index.php/Keyboard_configuration_in_Xorg#Configuring_compose_key>.
<a id="orgaba3aca"></a>
# Notes et références sur la séquence 5 : « Les étiquettes et les logiciels d'indexation pour s'y retrouver »
<a id="orgfcff6c0"></a>
## La structure de la séquence
Nous revenons ici sur le problème de l'indexation, pas tant sur l'indexation d'un document unique que sur l'indexation de documents multiples dans des formats divers :
- comme nous l'avons déjà affirmé, prendre des notes abondantes et détaillées n'est utile que si nous pouvons retrouver les informations qu'elles contiennent quand nous en avons besoin ;
- pour des notes contenues dans un seul fichier texte, la fonction de recherche de notre éditeur favori nous permet généralement d'aller assez loin ;
- pour des notes manuscrites contenues dans un cahier, la méthode de Locke — que nous avons exposée dans notre deuxième séquence — et qui repose sur des mots clé ou étiquettes, donne de bons résultats ;
- les notes manuscrites sur fiches sont généralement stockées dans un meuble dont la structure matérialise un index — comme l'armoire de Placcius et Leibniz — ;
- mais nous voulons ici aller plus loin, dans le cadre restreint des « notes » numérisées, en discutant de l'indexation de fichiers multiples qu'ils soient au format « texte » où dans d'autres format comme les images `jpg` où les fichier `pdf` ;
- cela nous amménera à introduire les « moteurs de recherche de bureau » et à expliquer comment des `étiquettes` ou `mots-clés` peuvent être ajoutés à nos fichiers.
<a id="org32aaaed"></a>
## La citation de Leibniz
J'ai trouvé la citation introductive :
« Il me semble que l'apparat savant contemporain est comparable à un grand magasin qui contient une grande quantité de produits, stockés de façon totalement désordonnée, mélangée ; où les nombres ou lettres d'indexation manquent ; où les inventaires et livres de comptes pouvant aider à ordonner le contenu ont disparus.
Plus grande est la quantité d'objets amassés, plus petite est leur utilité. Ainsi, ne devrions nous pas seulement essayer de rassembler de nouveaux objets de toutes provenances, mais nous devrions aussi essayer d'ordonner ceux que nous avons déjà. »
sur le site <http://www.backwordsindexing.com/index.html>, c'est donc une traduction de traduction. J'emploie ici le terme volontairement anachronique d'« [apparat savant](<https://fr.wikipedia.org/wiki/Apparat_savant>) » qui est un terme technique de l'édition désignant : citations, références et sources, notes en bas de pages, introduction, texte en langue originale (en parallèle avec la traduction), commentaire historique ou philologique, index fontium (les sources), index locorum (références avec renvoi à la page où le passage est cité ou mentionné, par ex. : Évangile selon Marc 1, 1 : p. 100), index nominum (les noms propres), index rerum (les thèmes), etc. La référence au « grand magasin » est, elle aussi anachronique !
Leibniz a, pendant une bonne partie de sa vie, « gagné celle-ci » comme [bibliothécaire](https://www.reseau-canope.fr/savoirscdi/societe-de-linformation/le-monde-du-livre-et-des-medias/histoire-du-livre-et-de-la-documentation/biographies/leibniz-le-bibliothecaire.html), ce qui explique en partie sont intérêt très poussé pour les questions de classifications, d'indexations, etc.
<a id="orgdbf92e1"></a>
## Rechercher avec un éditeur de texte
La diapo correspondante rappelle juste au lecteur quelque chose qu'il sait déjà et qui est vue, par les gens qui passent des notes « papier » aux notes « numériques », comme le gros attrait du numérique.
Les gens de monde Unix/Linux connaissent aussi généralement le programme [grep](https://fr.wikipedia.org/wiki/Grep) qui permet de faire des recherches de mots et, plus généralement d'[expressions régulières](https://fr.wikipedia.org/wiki/Expression_r%C3%A9guli%C3%A8re), sur un ou *plusieurs* fichiers ; nous y reviendrons.
<a id="orgab1d546"></a>
## Recherche avec index construit « à la main » sur des cahiers de notes
Là encore, il s'agit juste d'un rappel pour les lecteurs assidus de ce cours ; à ce stade se sont des experts dans la méthode d'indexation de Locke.
<a id="orgebb0a49"></a>
## Recherche avec index « matérialisés »
Encore un rappel pour les lecteurs.
<a id="orgddef543"></a>
## Vers les outils « sophistiqués » de l'informatique
- les techniques que nous venons de voir ou revoir ne fonctionnent que pour un seul « document » — recherche avec l'éditeur de texte, index d'un cahier — et/ou pour un seul type de document ;
- les outils informatiques dont nous disposons nous permettent d'aller plus loin dans l'indexation des fichiers numériques ;
- il est possible de rajouter des étiquettes ou mots-clés à des fichiers textes comme à des fichiers images (\`jpg\`, \`png\`) ou des fichiers « mixtes » (\`pdf\`) grâce aux métadonnées qu'ils contiennent ;
- les moteurs de recherche de bureau permettent d'indexer l'ensemble des fichiers textes d'une arborescence donnée mais aussi les métadonnées des autres fichiers.
<a id="orgaf4f7ba"></a>
## Les moteurs de recherche de bureau
Les moteurs de recherche de bureau comme :
- [DocFetcher](http://docfetcher.sourceforge.net/fr/index.html) (Linux, MacOS, Windows) ;
- [Tracker](https://wiki.gnome.org/Projects/Tracker) (Linux) ;
- [Recoll](https://www.lesbonscomptes.com/recoll/index.html.fr) (Linux, MacOS, Windows) ;
- [Spotlight](https://fr.wikipedia.org/wiki/Spotlight_(moteur_de_recherche)) (MacOS) ;
permettent de rechercher le *contenu* des fichiers textes, des courriels, des fichiers générés par les `traitements de texte` — c'est-à-dire des fichiers qui contiennent essentiellement du texte, mais qui sont stockés dans un format type `doc`, `docx`, `odt`, etc qui ne sont pas des formats texte —, des fichiers `pdf` — quand ceux-ci ne sont pas des *images* de textes —, mais aussi des [métadonnées](https://en.wikipedia.org/wiki/Portable_Document_Format#Metadata) des fichiers `pdf`, etc.
Les moteurs de recherche de bureau « utilisent des techniques d'[indexation](https://fr.wikipedia.org/wiki/Indexation_automatique_de_documents) qui permettent de réduire considérablement les temps de recherche, par rapport aux fonctions de recherche intégrées par défaut aux systèmes d'exploitation. Au contraire de ces derniers, ils prennent aussi souvent en charge les [métadonnées](https://fr.wikipedia.org/wiki/M%C3%A9tadonn%C3%A9e), et sont capables de faire une [analyse syntaxique](https://fr.wikipedia.org/wiki/Analyse_syntaxique) des fichiers. » (Source : [Moteur de recherche de bureau](https://fr.wikipedia.org/wiki/Moteur_de_recherche_de_bureau) sur Wikipédia)
Comme exemple de « fonctions de recherche intégrées par défaut », on trouvera sur les systèmes Unix/Linux le programme [grep ](https://fr.wikipedia.org/wiki/Grep)avec lequel nous pouvons chercher les occurrences du mot « Galilée » dans le répertoire « RR\_MOOC » de notre cours sur GitHub (après l'avoir cloné) :
grep -r Galilée
Notes_module1.org:- [[https://en.wikipedia.org/wiki/Galileo_Galilei][la page wikipedia sur Galilée]] contient de nombreux liens, certains vers ses cahiers de notes ;
Notes_module1.org:Comme exemple de « fonctions de recherche intégrées par défaut », on trouvera sur les systèmes Unix/Linux le programme [[https://fr.wikipedia.org/wiki/Grep][grep ]]avec lequel nous pouvons chercher les occurrences du mot « Galilée » dans le répertoire « RR_MOOC » de notre cours sur GitHub (après l'avoir cloné) :
Notes_module1.org:grep -r Galilée
Notes_module1.org:: PITCHME.md:## Galilée qui observe les lunes de Jupiter
Notes_module1.org:: PITCHME.md:Le 7 janvier 1610, Galilée fait une découverte capitale : il remarque trois « petites étoiles » à côté de Jupiter. Après quelques nuits d'observation, il découvre qu'il y en a une quatrième et qu'**elles accompagnent la planète**, c'est ce qu'il note sur son cahier d'observations. Ce sont les satellites visibles de Jupiter, qu'il nommera plus tard les étoiles Médicées ou astres médicéens – en l'honneur de ses protecteurs, la Famille des Médicis – et qui sont aujourd'hui appelés lunes galiléennes.
Notes_module1.org:: PITCHME.md:Ces observations amèneront Galilée à rejeter l'hypothèse géocentrique (la terre est le centre de l'Univers et tout tourne autour d'elle) en faveur du système copernicien héliocentrique. Cela l'amènera indirectement (je « fais court ») et bien plus tard, le 22 juin 1633, a être condamné par l'inquisition, ce qui lui vaudra de finir ses jours en résidence surveillée.
Notes_module1.org:: PITCHME.md:Remarquez l'avantage des « bouts de papiers classés » de Placcius et Leibniz sur le _codex_ de Galilée : les premiers peuvent être facilement réordonnées.
Notes_module1.org:: Notes_module1.org:- [[https://en.wikipedia.org/wiki/Galileo_Galilei][la page wikipedia sur Galilée]] contient de nombreux liens, certains vers ses cahiers de notes ;
Notes_module1.org:: Notes_module1.org:Comme exemple de « fonctions de recherche intégrées par défaut » on trouvera sur les systèmes Unix/Linux le programme [[https://fr.wikipedia.org/wiki/Grep][grep ]]avec lequel nous pouvons chercher les occurrences du mot « Galilée » dans le répertoire « RR_MOOC » de notre cours sur GitHub (après l'avoir cloné) :
Notes_module1.org:: Notes_module1.org:grep -r Galilée
PITCHME.md:## Galilée qui observe les lunes de Jupiter
PITCHME.md:Le 7 janvier 1610, Galilée fait une découverte capitale : il remarque trois « petites étoiles » à côté de Jupiter. Après quelques nuits d'observation, il découvre qu'il y en a une quatrième et qu'**elles accompagnent la planète**, c'est ce qu'il note sur son cahier d'observations. Ce sont les satellites visibles de Jupiter, qu'il nommera plus tard les étoiles Médicées ou astres médicéens – en l'honneur de ses protecteurs, la Famille des Médicis – et qui sont aujourd'hui appelés lunes galiléennes.
PITCHME.md:Ces observations amèneront Galilée à rejeter l'hypothèse géocentrique (la terre est le centre de l'Univers et tout tourne autour d'elle) en faveur du système copernicien héliocentrique. Cela l'amènera indirectement (je « fais court ») et bien plus tard, le 22 juin 1633, a être condamné par l'inquisition, ce qui lui vaudra de finir ses jours en résidence surveillée.
PITCHME.md:Remarquez l'avantage des « bouts de papiers classés » de Placcius et Leibniz sur le _codex_ de Galilée : les premiers peuvent être facilement réordonnées.
Une version plus sophistiquée de `grep` est fournie par le programme [cgvg](http://uzix.org/cgvg.html).
<a id="org06edb53"></a>
## Pourquoi des étiquettes
Une requête basée sur un simple mot renvoie souvent un très grand nombre de propositions, même si la plupart des moteurs de recherche de bureau permettent de filtrer ces dernières. Une façon efficace de limiter leur nombre est d'inclure dans nos documents des étiquettes, c'est-à-dire des points d'ancrage labelisés, qui seront aisément indexés par le moteur de recherche de bureau et dont le label ne correspond à aucun mot ou locution du dictionnaire — nous effectuons ainsi une version simplifiée du travail de l'*indexeur*, la personne chargée de construire l'index d'un livre. Pour que l'étiquette garde un sens, il suffit d'encadrer un mot par une paire de signes de ponctuation comme « : », « ; » ou « ? ». Un label comme « :code: » sera facilement mémorisé et fera un parfait équivalent du mot-clé « code » utilisé dans l'exemple du cahier de note de la deuxième séquence de ce module — pour illustrer la méthode de Locke.
Il nous reste encore nous reste encore un détail technique à régler dans le cas de nos notes prises en format texte comme `Markdown`. En effet, nous ne souhaitons pas que nos étiquettes apparaissent dans les sorties `html`, `pdf` ou `docx` de nos notes. Un façon de procéder, pour les langages de balisage légers qui ne disposent pas d'étiquettes — par exemple, `Markdown` n'en dispose pas, alors que `org` en a — et de les inclure dans des commentaires. En `Markdown`, tout ce qui est encadré par `<!--` et `-->` est considéré comme un commentaire et ne figure pas dans les sorties `html` ou `pdf` des notes. Nous pouvons ainsi utiliser :
<!-- ;code; -->
à l'endroit de nos notes où nous souhaitons aller rapidement lorsque que nous cherchons une information relative à de la programmation (production de codes).
<a id="orgd05cefb"></a>
## Les métadonnées
<a id="org35c9a2a"></a>
### Fichiers images
Nous savons à présent comment rajouter des étiquettes à un fichier au format texte, mais nous devons souvent aussi travailler avec des fichiers contenant des images ou des photos, comme les fichiers [JPEG](https://fr.wikipedia.org/wiki/JPEG) — les appareils photos numériques utilisent tous ce format —, [GIF](https://fr.wikipedia.org/wiki/Graphics_Interchange_Format) ou [PNG](https://fr.wikipedia.org/wiki/Portable_Network_Graphics). La question se pose alors, peut-on ajouter des étiquettes à nos fichiers images de sorte que nos moteurs de recherche de bureau les indexent ? La réponse et oui, grâce aux [métadonnées](https://fr.wikipedia.org/wiki/M%C3%A9tadonn%C3%A9e) que contiennent ces fichiers. Les métadonnées, dans ce cas, sont des données stockées dans le fichier mais qui ne sont pas montrées par le logiciel de rendu (en tout cas, pas montrées par défaut). Nous savons tous que ces métadonnées « existent » ; ce sont elles qui contiennent la date, la localisation GPS, le temps d'exposition, etc. de nos photos numériques. Dans les fichiers `JPEG`, elles sont stockées suivant l'[exchangeable image file format](https://fr.wikipedia.org/wiki/Exchangeable_image_file_format) (`EXIF`). La plupart des logiciels de manipulations d'images et de photos permettent d'accéder au contenu des métadonnées et de les modifier. L'exemple illustré dans le cours utilise une solution très simple en « ligne de commande », [ExifTool](http://owl.phy.queensu.ca/~phil/exiftool/) qui permet de visualiser et de modifier les métadonnées. D'autres logiciels comme [exiv2](http://www.exiv2.org/index.html) ou [ImageMagick](https://imagemagick.org/script/index.php) permettent de le faire (pour ne citer que des logiciels libres disponibles sur Linux, Windows et MacOS). Certains des éléments du format `EXIF` sont des chaînes de caractères, c'est-à-dire du texte, que nous somme libres d'utiliser comme nous le souhaitons ; nous pouvons dès lors les utiliser pour rajouter nos étiquettes. Nous illustrons dans le cours comment le faire avec `ExifTool`, mais nous aurions aussi pu le faire avec le programme [mogrify](https://www.imagemagick.org/script/command-line-options.php#comment) d'ImageMagick. Tous les moteurs de recherche de bureau que nous avons mentionné vont « aller regarder » les métadonnées des fichier `JPEG` lors de la phase d'indexation et nous permettront ainsi d'exploiter les étiquettes que nous y aurons insérées.
`EXIF` n'est pas le seul format de métadonnées existant ; un format plus récent est l'[Extensible Metadata Platform ](https://fr.wikipedia.org/wiki/Extensible_Metadata_Platform)(`XMP`), disponible pour un plus grand nombre de formats de fichiers — il n'est pour l'instant pas lu sur les fichiers `JPEG` par `DocFetcher`, c'est pourquoi nous avons mis en avant le format `EXIF`, mais cela devrait évoluer assez vite ; les autres moteurs comme `Tracker` et `Recoll` le lisent.
<a id="org1dca817"></a>
### Fichiers `PDF`
En plus des fichiers images, nous sommes tous très fréquemment amenés à travailler avec les fichiers « composites » — contenant textes, images, et plus — que sont les fichiers [PDF](https://fr.wikipedia.org/wiki/Portable_Document_Format). Ces fichiers contiennent eux aussi des métadonnées ; c'est d'ailleurs pour eux qu'Adobe a initialement introduit le format `XMP` que nous venons de discuter. Ces métadonnées peuvent être lues et modifiées, en particulier l'élément `Keywords` (mot-clé) qui peut contenir des chaînes de caractères de longueur arbitraires et qui est parfait pour accueillir nos étiquettes. Le programme `ExifTool`, permet de modifier les métadonnées des fichiers `PDF`. Les moteurs de recherche de bureau que nous avons mentionnés, vont tous aller lire les métadonnées des fichiers `PDF` lors de la phase d'indexation.
<a id="orgea7f02d"></a>
### Fichiers audios
Les formats audio comme le [mp3](https://fr.wikipedia.org/wiki/MPEG-1/2_Audio_Layer_III) ou le [ogg](https://fr.wikipedia.org/wiki/Ogg) contiennent eux aussi des métadonnées, où sont stockés les titres, noms des interprètes, etc ; ces métadonnées peuvent être modifiées et sont lues par les moteurs de recherche de bureau lors de la phase d'indexation.
module1/slides/misc/description_sequences_module1.md deleted 100644 → 0
View file @ 8986dad7
# Table of Contents
1. [Séquence 1](#org89df9e0)
2. [Séquence 2](#org45e2627)
3. [Séquence 3](#org7d9ab98)
4. [Séquence 4](#org6f03fc8)
5. [Sèquence 5](#org95c7511)
<a id="org89df9e0"></a>
# Séquence 1
- Quelques exemples, célèbres et moins célèbres, de prise de notes.
- Some famous and less famous examples of note-taking.
<a id="org45e2627"></a>
# Séquence 2
- Une courte histoire de la navigation dans le livre et les notes.
- A brief history of navigation within the book and notes.
<a id="org7d9ab98"></a>
# Séquence 3
- L'intérêt des fichiers textes et des langages de balisage légers.
- Why should we use text fromats and ligthweight markup languages?
<a id="org6f03fc8"></a>
# Séquence 4
- Comment archiver des notes tout en les faisant évoluer ? L'intérêt des logiciels de gestion de version.
- How to archive notes while letting them evolve? The case for version control systems.
<a id="org95c7511"></a>
# Sèquence 5
- S'y retrouver dans ses notes avec des mots-clés et un moteur de recherche de bureau.
- Finding one's way in a large notes collection with key-words and desktop search software.
module2/ressources/emacs_orgmode.md deleted 100644 → 0
View file @ 8986dad7
---
title: Emacs/org-mode
date: Wed Mar 20 16:01:41 2019
---
**Disclaimer:** The two sections *A simple "reproducible research" emacs
configuration* and *A stub of replicable article* explain how to set up
emacs/org-mode for this MOOC. These are very important sections in the
context of this MOOC. **These sections are illustrated in two out of the
[three video tutorials of this
sequence](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4),
and** **which you really should follow carefully**. **Otherwise, you may
have trouble doing the exercises later on**. Likewise, I strongly
encourage you to watch the ["emacs and git" video tutorial available at
the same
place](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4).
The next section provides information on how to install
emacs.
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Installing emacs, org-mode, ess, and
auctex.](#installing-emacs-org-mode-ess-and-auctex)
- [Linux (Debian, Ubuntu)](#linux-debian-ubuntu)
- [macOS](#macos)
- [Windows](#windows)
- [All platforms: pretty code in HTML
export](#all-platforms-pretty-code-in-html-export)
- [A simple "reproducible research" emacs
configuration](#a-simple-reproducible-research-emacs-configuration)
- [Step 0: Backup and download our
configuration](#step-0-backup-and-download-our-configuration)
- [Step 1: Prepare your journal](#step-1-prepare-your-journal)
- [Step 2: Set up Emacs
configuration](#step-2-set-up-emacs-configuration)
- [Step 3: Adapt the configuration to your specific needs if
required](#step-3-adapt-the-configuration-to-your-specific-needs-if-required)
- [Step 4: Check whether the installation is working or
not](#step-4-check-whether-the-installation-is-working-or-not)
- [Step 5: Open and play with your
journal:](#step-5-open-and-play-with-your-journal)
- [A stub of a replicable article](#a-stub-of-a-replicable-article)
- [Emacs tips and tricks](#emacs-tips-and-tricks)
- [Cheat-sheets](#cheat-sheets)
- [Video tutorials](#video-tutorials)
- [Additional useful emacs
packages](#additional-useful-emacs-packages)
- [Other resources](#other-resources)
# Installing Emacs
In the following we describe for each platform the installation method
that we consider most convenient. There are other options that may be
preferable in particular situations, so you may want to look at the
[Emacs Web site](https://www.gnu.org/software/emacs/download.html) for
details, but we strongly suggest you first try the method we recommend.
At the end of the installation procedure, you should have one of
1. Emacs 26 (the latest version)
2. Emacs 25 plus Org-Mode 9
Emacs 25 comes with Org-Mode 8, which is not compatible with our
examples. So if you use Emacs 25, you must separately install Org-Mode
9. Emacs 26 already includes Org-Mode 9.
Our MOOC also requires a few extra Emacs packages:
[ESS](https://ess.r-project.org/) (for working with the R language) and
[AUCTeX](https://www.gnu.org/software/auctex/) (for editing LaTeX). They
will be installed automatically the first time you start Emacs if you
use the configuration described under [A simple "reproducible research"
emacs
configuration](#a-simple-reproducible-research-emacs-configuration).
## 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).
These are the versions of Emacs that various distributions provide:
- Debian (stretch) ships with
[emacs 25.1](https://packages.debian.org/stretch/emacs25) and
[org-mode 9.0.3](https://packages.debian.org/stretch/org-mode)
- Ubuntu (bionic 18.04) ships with
[emacs 25.2](https://packages.ubuntu.com/bionic/emacs25) and
[org-mode 9.1.6](https://packages.ubuntu.com/bionic/org-mode)
- Ubuntu (artful 17.04) ships with
[emacs 25.2](https://packages.ubuntu.com/artful/emacs25) and
[org-mode 9.0.9](https://packages.ubuntu.com/artful/org-mode)
If your distribution is older than this, well, it may be a good time for
upgrading…
Simply run (as root):
``` bash
apt-get update ; apt-get install emacs25 org-mode
```
Then verify that you have a sufficiently recent version of Emacs.
``` bash
emacs --version 2>&1 | head -n 1
```
``` example
GNU Emacs 25.2.2
```
Likewise, you'll want to check you have a recent version of Org-Mode:
``` bash
emacs -batch --funcall "org-version" 2>&1 | grep version
```
``` example
Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/)
```
The version numbers you get will depend on the distribution you are
running. <span class="underline">You really want to make sure you do not
rely on org-mode 8</span>, which is now deprecated.
## 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.
The Web site <https://emacsformacosx.com/> proposes precompiled Emacs
versions for macOS. Download the latest version (the one that figures
prominently on the page) and install it like you would install any other
macOS application, by copying `Emacs.app` from the downloaded disk image
to a convenient location on your computer.
In case you need to run Emacs from the command line (note: this is not
required for the MOOC), you have to enter the full path to the
executable. Assuming that you have copied `Emacs.app` to
`/path/to/emacs`, this is
`/path/to/emacs/Emacs.app/Contents/MacOS/Emacs`. If you just type
`emacs`, you will use the prehistoric command-line-only version at
`/usr/bin/emacs` provided by Apple.
## Windows
Download the [precompiled
Emacs 26.1](https://ftp.gnu.org/gnu/emacs/windows/emacs-26/emacs-26.1-i686.zip)
and unzip the zip file preserving the directory structure, and run
`bin\runemacs.exe`.
Alternatively, create a desktop shortcut to `bin\runemacs.exe`, and
start Emacs by double-clicking on that shortcut's icon. See
[here](https://www.gnu.org/software/emacs/manual/html_node/emacs/Windows-Startup.html)
for an explanation of this and other methods for launching Emacs under
Windows.
### Directory naming conventions
In the following instructions, we 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](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/).
### Installing and configuring Matplotlib (graphic python library)
Open an DOS console and type the following command:
``` shell
python -m pip install -U matplotlib
```
![](emacs_orgmode_images/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:
``` python
import matplotlib
matplotlib.matplotlib_fname()
```
![](emacs_orgmode_images/matplotlib.png)
Open the `matplotlibrc` file and modify the line starting with `backend`
to make it `backend : Agg`.
# A simple "reproducible research" emacs configuration
This section is illustrated in a [video
tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4)
(*"Mise en place Emacs/Orgmode"* in French). Watching it before
following the instructions given in this section may help.
Emacs comes with a very basic default configuration, so almost everyone
wants to personalize it. Given the flexibility of Emacs, a configuration
can become quite complex and in fact include what would otherwise be
considered complete software packages. In the context of this MOOC, we
propose a relatively minimalist configuration oriented towards
"*reproducible research*" with Org-Mode. If you are new to Emacs, we
strongly recommended that you use it with as little modification as
possible, by following the instructions in this section. If you are a
more experienced Emacs user, you can go through the instructions and
adopt the pieces that you consider useful for you.
It is unfortunately rather probable that some of you will run into
unforeseen problems with this configuration. If that is your case, ask a
question on the forum. We will do our best to help you.
## Step 0: Backup and remove your previous configuration
If you have used Emacs before, you may already have a personal
configuration. And even if not, you may have Emacs configuration files
without being aware of them, since some software packages create or
modify Emacs configuration files. In order to avoid trouble, remove
prior configurations, after making a backup elsewhere.
The files that you should backup and then remove (if they exist) are:
1. `~/.emacs`
2. `~/.emacs.el`
3. `~/.emacs.elc`
There is also a directory that you should backup and then remove (if it
exists), with everything it might contain:
1. `~/.emacs.d`
In the above filenames, `~/` stands for your home directory. Windows
users should replace it by `C:\Users\MyName`, replacing MyName by their
user name.
## Step 1: Download our configuration
Download [this
archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org_archive.tgz)
and uncompress it. It contains the following files and we will refer to
them in the following:
``` example
rr_org/init.el
rr_org/journal.org
```
Alternatively, [the files you are looking for are available
here](rr_org/).
If you use Windows, and if you use a desktop shortcut to start Emacs,
you must include the path to the file `init.el` in the command for the
shortcut. For example, if you installed Emacs as
`C:\Users\MyName/emacs`, your desktop shortcut should execute the
command `C:\Users\MyName\emacs\bin\runemacs.exe -l .emacs.d/init.el`.
## Step 2: Prepare your journal
Create an `org/` directory in the top of your home:
``` bash
mkdir -p ~/org/
```
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 [many Emacs
shortcuts](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
that you should give a try.
## Step 3: Put the Emacs configuration file in the right place
Create the directory `~/.emacs.d/` and copy `rr_org/init.el` into it.
## Step 4: 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. 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.
If you do have to modify `init.el`, check the comments at the beginning
of the file for instructions.
## Step 5: Check whether the installation is working or not
Quit Emacs if it is running, and start it again. This first start will
take a bit of time because Emacs will download a few add-on packages.
For that reason, please make sure that you have a working internet
connection for this step.
Then open a file `foo.org`. Copy the following lines into this file:
``` example
#+begin_src shell :session foo :results output :exports both
ls -la # or dir under windows
#+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 [first entry of your
labbook](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org).
## Step 6: Open and play with your journal:
In step 2, you were told to create a journal in `~org/journal.org`. You
probably want to make sure this file is stored in a version 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 MOOC forum.
# A stub of a replicable article
This section is illustrated in a [video
tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4)
(*"Écrire un article réplicable avec Emacs/Orgmode"* in French).
Watching it before following the instructions given in this section may
help.
Remember, you need a working LaTeX and R environment. If you can't open
a terminal and run the commands `R`, `pdflatex`, and `python`, you will
not be able to generate this document. When being compiled, the article
downloads the corresponding LaTeX packages so you also need to have a
working `wget` command (alternatively, it uses `curl`). Once downloaded,
you may still read the source
(<https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org>)
and understand how it works though.
Download the following
[archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz),
uncompress it and simply `make` to generate the article. You should then
be able to open the [resulting
article](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf).
This is summarized in the following
command:
``` bash
wget --no-check-certificate -O replicable_article.tgz https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz
tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf
```
**Possible issues**:
- If the `make` command fails (especially on Mac), it may be because
Emacs or something else is not correctly installed. In that case,
open the article directly with the following
command:
``` bash
emacs -q --eval "(setq enable-local-eval t)" --eval "(setq enable-local-variables t)" article.org
```
and export it to pdf with the following shortcut: `C-c C-e l o`
- If it still doesn't work and emacs complains about not finding ESS,
it may be because you installed ESS in your home instead of
system-wide. In that case, try to remove the `-q` in the previous
command line to load your personal emacs configuration.
Finally, when you'll be tired of always re-executing all the source code
when exporting, just look for the following line in
[article.org](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org):
``` example
# #+PROPERTY: header-args :eval never-export
```
If you remove the `# ` in the beginning of the line, it will not be a
comment anymore and will indicate org-mode to stop evaluating every
chunk of code when exporting.
# 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
- [Common and step-by-step Emacs shortcuts for our *reproducible
research*
configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
- [The official GNU emacs
refcard](https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf)
- Two graphical cheat-sheats by Sacha Chua on
![](http://sachachua.com/blog/wp-content/uploads/2013/05/How-to-Learn-Emacs-v2-Large.png)
and on
![](http://sachachua.com/blog/wp-content/uploads/2013/08/20130830-Emacs-Newbie-How-to-Learn-Emacs-Keyboard-Shortcuts.png).
### Org-mode
- [Common and step-by-step org-mode shortcuts for our *reproducible
research*
configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
- [The official org-mode
refcard](https://orgmode.org/worg/orgcard.html)
- [The official description of the org-mode
syntax](https://orgmode.org/worg/dev/org-syntax.html) and a
[relatively concise description of the org-mode
syntax](https://gist.github.com/hoeltgman/3825415).
## Video tutorials
For those of you who prefer video explanations, here is a [Youtube
channel with many step by step emacs
tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg).
## Additional useful emacs packages
### Company-mode
[Company-mode](http://company-mode.github.io/) 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 Web page:
<http://company-mode.github.io/>
### Magit
[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is
briefly illustrated in the context of this MOOC in a [video
tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4)
("*Utilisation Emacs/git*" in French).
It is very powerful and we use it on a daily basis but you should
definitely understand what git does behind the scenes beforehand. If you
feel this would be useful for you, you should follow [this visual
walk-through](https://magit.vc/screenshots/) or [this really short
"crash course"](https://www.emacswiki.org/emacs/Magit). If you installed
the previous "*reproducible research*" emacs configuration, you can
easily invoke magit by using `C-x g`.
## Other resources
- [The compact Org-mode Guide](https://orgmode.org/orgguide.pdf)
- [Many examples illustrating the use of different languages in
org-mode](https://github.com/dfeich/org-babel-examples)
module2/ressources/emacs_orgmode_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: FIXME Emacs/org-mode
date: Thu Feb 21 17:05:51 2019
---
**Disclaimer:** The two sections *A simple "reproducible research" emacs
configuration* and *A stub of replicable article* explain how to set up
emacs/org-mode for this MOOC. These are very important sections in the
context of this MOOC. **These sections are illustrated in two out of the
[three video tutorials of this
sequence](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4),
and** **which you really should follow carefully**. **Otherwise, you may
have trouble doing the exercises later on**. Likewise, I strongly
encourage you to watch the ["emacs and git" video tutorial available at
the same
place](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4).
The next section provides information on how to install
emacs.
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Installing emacs, org-mode, ess, and
auctex.](#installing-emacs-org-mode-ess-and-auctex)
- [Linux (Debian, Ubuntu)](#linux-debian-ubuntu)
- [macOS](#macos)
- [Windows](#windows)
- [All platforms: pretty code in HTML
export](#all-platforms-pretty-code-in-html-export)
- [A simple "reproducible research" emacs
configuration](#a-simple-reproducible-research-emacs-configuration)
- [Step 0: Backup and download our
configuration](#step-0-backup-and-download-our-configuration)
- [Step 1: Prepare your journal](#step-1-prepare-your-journal)
- [Step 2: Set up Emacs
configuration](#step-2-set-up-emacs-configuration)
- [Step 3: Adapt the configuration to your specific needs if
required](#step-3-adapt-the-configuration-to-your-specific-needs-if-required)
- [Step 4: Check whether the installation is working or
not](#step-4-check-whether-the-installation-is-working-or-not)
- [Step 5: Open and play with your
journal:](#step-5-open-and-play-with-your-journal)
- [A stub of a replicable article](#a-stub-of-a-replicable-article)
- [Emacs tips and tricks](#emacs-tips-and-tricks)
- [Cheat-sheets](#cheat-sheets)
- [Video tutorials](#video-tutorials)
- [Additional useful emacs
packages](#additional-useful-emacs-packages)
- [Other resources](#other-resources)
# Installing emacs, org-mode, ess, and auctex.
## 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
[emacs 25.1](https://packages.debian.org/stretch/emacs25) and
[org-mode 9.0.3](https://packages.debian.org/stretch/org-mode)
- Ubuntu (bionic 18.04) ships with
[emacs 25.2](https://packages.ubuntu.com/bionic/emacs25) and
[org-mode 9.1.6](https://packages.ubuntu.com/bionic/org-mode)
- Ubuntu (artful 17.04) ships with
[emacs 25.2](https://packages.ubuntu.com/artful/emacs25) and
[org-mode 9.0.9](https://packages.ubuntu.com/artful/org-mode)
If your distribution is older than this, well, it may be a good time for
upgrading…
Simply run (as root):
``` bash
apt-get update ; apt-get install emacs25 org-mode ess r-base auctex
```
Then make sure you have a sufficiently recent version of emacs.
``` bash
emacs --version 2>&1 | head -n 1
```
``` example
GNU Emacs 25.2.2
```
Likewise, you'll want to check you have a recent version of org-mode:
``` bash
emacs -batch --funcall "org-version" 2>&1 | grep version
```
``` example
Org mode version 9.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/)
```
The version numbers you get will depend on the distribution you are
running. <span class="underline">You really want to make sure you do not
rely on org-mode 8</span>, which is now deprecated.
## 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.
The Web site <https://emacsformacosx.com/> proposes precompiled Emacs
versions for macOS. Download the latest version (the one that figures
prominently on the page) and install it like you would install any other
macOS application, by copying `Emacs.app` from the downloaded disk image
to a convenient location on your computer.
This Emacs version contains everything used in the MOOC except the
packages [ESS](https://ess.r-project.org/) (for working with the R
language) and [AUCTeX](https://www.gnu.org/software/auctex/) (for
editing LaTeX). If you use the configuration described under [A simple
"reproducible research" emacs
configuration](#a-simple-reproducible-research-emacs-configuration),
these packages will be installed automatically the first time you start
Emacs.
In case you need to run Emacs from the command line (note: this is not
required in the MOOC), you have to enter the full path to the
executable. Assuming that you have copied `Emacs.app` to
`/path/to/emacs`, this is
`/path/to/emacs/Emacs.app/Contents/MacOS/Emacs`. Note that if you just
type `emacs`, you will use the prehistoric command-line-only version at
`/usr/bin/emacs` provided by Apple.
## Windows
Install the `.exe` file from [Vincent
Goulet](http://vgoulet.act.ulaval.ca/):
<https://vigou3.gitlab.io/emacs-modified-windows/>. It ships with recent
versions:
- Emacs 26.1
- Org-mode 9.1.13
- ESS 17.11
### Directory naming conventions
In the following instructions, we 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](http://sametmax.com/ajouter-un-chemin-a-la-variable-denvironnement-path-sous-windows/).
### Installing and configuring Matplotlib (graphic python library)
Open an DOS console and type the following command:
``` shell
python -m pip install -U matplotlib
```
![](emacs_orgmode_images/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:
``` python
import matplotlib
matplotlib.matplotlib_fname()
```
![](emacs_orgmode_images/matplotlib.png)
Open the `matplotlibrc` file and modify the line starting with `backend`
to make it `backend : Agg`.
## All platforms: pretty code in HTML export
To have code pretty printing when exporting to HTML, you should install
the `htmlize` package, which is done by opening emacs and typing the
following
command:
``` example
M-x package-install RET htmlize RET # where M-x means pressing the "Esc" key then the "x" key
```
# A simple "reproducible research" emacs configuration
This section is illustrated in a [video
tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4)
(*"Mise en place Emacs/Orgmode"* in French). Watching it before
following the instructions given in this section may help.
Emacs comes with very basic default configuration and it appears like
everyone has its own taste. You will for example find
[here](https://www.emacswiki.org/emacs/StarterKits) several default
Emacs configurations that reflect the preferences of their creators.
Likewise the configuration of Org-Mode is incredibly flexible (see for
example [the org-mode
website](https://orgmode.org/worg/org-configs/index.html) for more
references). In the context of this MOOC, we propose you a relatively
minimalist one that is rather "*reproducible research*" oriented by
adding a few org-mode specific configurations.
## Step 0: Backup and download our configuration
The procedure we propose will wipe your already existing custom Emacs
configuration if you have one. **You should thus beforehand make a
backup** of `~/.emacs` and of `~/.emacs.d/init.el` (if these files
exist).
Then download [this
archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/rr_org_archive.tgz)
and uncompress it. It contains the following files and we will refer to
them in the following:
``` example
rr_org/init.el
rr_org/journal.org
```
Alternatively, [the files you are looking for are available
here](rr_org/).
## Step 1: Prepare your journal
Create an `org/` directory in the top of your home:
``` bash
mkdir -p ~/org/
```
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 [many Emacs
shortcuts](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
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: 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. 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.
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:
``` example
#+begin_src shell :session foo :results output :exports both
ls -la # or dir under windows
#+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 [first entry of your
labbook](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org).
## 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 stored in a version
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 a replicable article
This section is illustrated in a [video
tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4)
(*"Écrire un article réplicable avec Emacs/Orgmode"* in French).
Watching it before following the instructions given in this section may
help.
Remember, you need a working LaTeX and R environment. If you can't open
a terminal and run the commands `R`, `pdflatex`, and `python`, you will
not be able to generate this document. When being compiled, the article
downloads the corresponding LaTeX packages so you also need to have a
working `wget` command (alternatively, it uses `curl`). Once downloaded,
you may still read the source
(<https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org>)
and understand how it works though.
Download the following
[archive](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz),
uncompress it and simply `make` to generate the article. You should then
be able to open the [resulting
article](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.pdf).
This is summarized in the following
command:
``` bash
wget --no-check-certificate -O replicable_article.tgz https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/replicable_article.tgz
tar zxf replicable_article.tgz; cd replicable_article; make ; evince article.pdf
```
**Possible issues**:
- If the `make` command fails (especially on Mac), it may be because
Emacs or something else is not correctly installed. In that case,
open the article directly with the following
command:
``` bash
emacs -q --eval "(setq enable-local-eval t)" --eval "(setq enable-local-variables t)" article.org
```
and export it to pdf with the following shortcut: `C-c C-e l o`
- If it still doesn't work and emacs complains about not finding ESS,
it may be because you installed ESS in your home instead of
system-wide. In that case, try to remove the `-q` in the previous
command line to load your personal emacs configuration.
Finally, when you'll be tired of always re-executing all the source code
when exporting, just look for the following line in
[article.org](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/replicable_article/article.org):
``` example
# #+PROPERTY: header-args :eval never-export
```
If you remove the `# ` in the beginning of the line, it will not be a
comment anymore and will indicate org-mode to stop evaluating every
chunk of code when exporting.
# 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
- [Common and step-by-step Emacs shortcuts for our *reproducible
research*
configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
- [The official GNU emacs
refcard](https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf)
- Two graphical cheat-sheats by Sacha Chua on
![](http://sachachua.com/blog/wp-content/uploads/2013/05/How-to-Learn-Emacs-v2-Large.png)
and on
![](http://sachachua.com/blog/wp-content/uploads/2013/08/20130830-Emacs-Newbie-How-to-Learn-Emacs-Keyboard-Shortcuts.png).
### Org-mode
- [Common and step-by-step org-mode shortcuts for our *reproducible
research*
configuration](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/rr_org/journal.org)
- [The official org-mode
refcard](https://orgmode.org/worg/orgcard.html)
- [The official description of the org-mode
syntax](https://orgmode.org/worg/dev/org-syntax.html) and a
[relatively concise description of the org-mode
syntax](https://gist.github.com/hoeltgman/3825415).
## Video tutorials
For those of you who prefer video explanations, here is a [Youtube
channel with many step by step emacs
tutorials](https://www.youtube.com/playlist?list=PL9KxKa8NpFxIcNQa9js7dQQIHc81b0-Xg).
## Additional useful emacs packages
### Company-mode
[Company-mode](http://company-mode.github.io/) 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 Web page:
<http://company-mode.github.io/>
### Magit
[Magit](https://magit.vc/) is an Emacs interface for Git. Its usage is
briefly illustrated in the context of this MOOC in a [video
tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/9cfc7500f0ef46d288d2317ec7b037b4)
("*Utilisation Emacs/git*" in French).
It is very powerful and we use it on a daily basis but you should
definitely understand what git does behind the scenes beforehand. If you
feel this would be useful for you, you should follow [this visual
walk-through](https://magit.vc/screenshots/) or [this really short
"crash course"](https://www.emacswiki.org/emacs/Magit). If you installed
the previous "*reproducible research*" emacs configuration, you can
easily invoke magit by using `C-x g`.
## Other resources
- [The compact Org-mode Guide](https://orgmode.org/orgguide.pdf)
- [Many examples illustrating the use of different languages in
org-mode](https://github.com/dfeich/org-babel-examples)
module2/ressources/gitlab.md deleted 100644 → 0
View file @ 8986dad7
---
title: Git and GitLab
date: Tue Feb 19 19:19:03 2019
---
**This document is particularly important if you follow the RStudio or
the Org-Mode path.** **If you follow the Jupyter path, it can be ignored
at first** **as we have closely integrated Jupyter and GitLab in the
context of this MOOC.**
So far, you only used git via the web interface from the GitLab we
deployed for the MOOC: <https://app-learninglab.inria.fr/gitlab/>
If you access this link from the FUN platform, you do not have to
authenticate and you can readily read and modify all your files. This is
very convenient but in most cases, you will want to have your own local
copy of the repository and you will have to synchronize your local copy
with the remote GitLab one. To propagate your modifications, you will
obviously have to authenticate yourself on GitLab.
This document describes the software you need to have installed on your
machine and how to handle authentication. The "Configuring Git" section
is illustrated in a [video
tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)
(in French).
Please read all these instructions carefully, in particular the one on
"Configuring your password on
GitLab".
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Installing Git](#installing-git)
- [Linux (Debian, Ubuntu)](#linux-debian-ubuntu)
- [Mac OSX and Windows](#mac-osx-and-windows)
- [Configuring Git](#configuring-git)
- [Telling Git who you are: Name and
Email](#telling-git-who-you-are-name-and-email)
- [Dealing with proxies](#dealing-with-proxies)
- [Getting your default password on GitLab (and possibly changing
it)](#getting-your-default-password-on-gitlab-and-possibly-changing-it)
- [Remembering your password
locally](#remembering-your-password-locally)
- [Optional: authenticating through
SSH](#optional-authenticating-through-ssh)
- [Using Git through the command line to synchronize your local files
with
Gitlab](#using-git-through-the-command-line-to-synchronize-your-local-files-with-gitlab)
# 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., RedHat, Fedora).
Run (as root):
``` bash
apt-get update ; apt-get install git
```
## Mac OSX and Windows
- Download and install Git from the [Git
website](https://git-scm.com/downloads).
- Optional Git clients (should not be needed if you work within
RStudio):
- [SourceTree](https://www.sourcetreeapp.com/)
- [GitHub Desktop](https://desktop.github.com/)
> [Apparently](https://github.com/desktop/desktop/issues/852),
> this works with GitLab and https.
# Configuring Git
## Telling Git who you are: Name and Email
1. Open terminal.
2. Set a Git username and email:
``` shell
git config --global user.name "Mona Lisa"
git config --global user.email "email@example.com"
```
3. Confirm that you have set the Git username correctly:
``` shell
git config --global user.name
git config --global user.email
```
``` example
Mona Lisa
email@example.com
```
## Dealing with proxies
You may be behind a proxy, in which case you may have trouble cloning or
fetching from a remote repository or you may get an error like `unable
to access ... Couldn't resolve host ...`
In such case, consider something like
this:
``` shell
git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port
```
The `proxyPassword` will be stored in plain text (unencrypted) in your
`.gitconfig` file, which you may not want. In that case, remove it from
the URL and you will be prompted for it every time it is needed.
## Getting your default password on GitLab (and possibly changing it)
**Warning (Jupyter users) :** changing your default Gitlab password will
prevent you from committing in Jupyter. You will have to do the extra
step of changing your `~/.git-credentials` in the Jupyter environment
(possibly several times).
1. Get your default password using the [Gitlab credentials retrieval
tool](https://app-learninglab.inria.fr/jupyterhub/services/password)
as described on the [corresponding
resource](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85).
<div class="CENTER">
![](gitlab_images/password_retrieval.png)
</div>
The first long and ugly character sequence is your GitLab login/id.
It is easy to find once you are logged on gitlab. The second one
however is your password and this webpage is the only place where
you can find it. We used the FUN authentification mechanism to
propagate your credentials so only you can have access to it. You'll
need to use this password when trying to propagate some
modifications from your computer to GitLab.
*Note: You have to access this webpage from the FUN platform
otherwise you may get a 405 error* *when trying to direcly open
<https://app-learninglab.inria.fr/jupyterhub/services/password>.*
<div class="CENTER">
![](gitlab_images/erreur405.png)
</div>
2. Access
[GitLab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/5571950188c946e790f06d4bc90fb5f6)
from the FUN plateform (click on "Accédez à Gitlab / Access to
Gitlab" Button).
*Note: Again, you have to access Gitlab from the FUN platform
otherwise you may get a 405 error* /when trying to direcly open
<https://app-learninglab.inria.fr/gitlab/users/sign_in/>.
3. Click on the first `Sign in` button (alternatively, you can the
login/password you just retrieved and use the second `Sign in`
button).
<div class="CENTER">
![](gitlab_images/signin.png)
</div>
4. If you wish to modify your password, you should go to `Account >
Settings > Password` and define your password using the default
password you just retrieved. Again, if you use the Jupyter notebooks
we have deployed for the MOOC, remember that changing your default
Gitlab password will prevent you from committing in Jupyter. You
will have to do the extra step of changing your Jupyter
`~/.git-credentials` through a Jupyter console (see next section).
<div class="CENTER">
![](gitlab_images/password.png)
</div>
## Remembering your password locally
If you clone your repository by simply pasting the GitLab URL, you will
be prompted for your login and your password every time you want to
propagate your local modifications, which is tedious. This is why you
should ask git to remember your login and password as
follows
``` shell
git config --global credential.helper cache # remember my password
git config --global credential.helper "cache --timeout=3600" # for one hour at most
```
With this setup, you will be prompted for your password but it will be
cached in memory and they will not be asked again before an hour. You
may want to read [these
instructions](https://stackoverflow.com/questions/5343068/is-there-a-way-to-skip-password-typing-when-using-https-on-github)
to better understand how all this works.
If you want your password to be permanently remembered, you should use
this command
``` shell
git config credential.helper store
```
Your password will be then stored in a `.git-credentials` file in plain
text. On a perfectly secured machine, it may be fine… or not… ;) Use it
at your own risk.
## Optional: authenticating through SSH
There are two ways of authenticating and synchronizing your local
repository with GitLab: through HTTPS or through SSH. The first one is
what was just described and does not require any particular software
installation on your machine so this is what I recommend for this MOOC.
Yet, I like the second one better (although is may seem a bit more
technical), which is why I describe it here. It consists in installing
SSH, creating a pair or private/public keys, and uploading your SSH
public key on GitLab. This section provides with information on how to
do this.
### Installing SSH
1. 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., RedHat, Fedora).
Run (as root):
``` bash
apt-get update ; apt-get install openssh-client
```
2. macOS
You do not have anything to do as it is installed by default.
3. Windows
You should install the
[Putty](https://www.ssh.com/ssh/putty/windows/) client. Once it is
installed, look for the section on [generating an SSH
key](https://www.ssh.com/ssh/putty/windows/puttygen).
### Setting up SSH on GitLab
Here are [all the official explanations on how to set up your SSH key on
GitLab](https://docs.gitlab.com/ee/ssh/). Alternatively, you may also
want to have a look at this
video:
<iframe width="560" height="315" src="https://www.youtube.com/embed/54mxyLo3Mqk" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
# Using Git through the command line to synchronize your local files with Gitlab
This section describes a generic (through the command line) way to
synchronize your local files with Gitlab. You will not need this if you
follow the Jupyter path. If you follow the RStudio path, all these
operations can be done through RStudio and you may want to read [the
corresponding
instructions](file:///jump_to_id/1a4f58a1efed437c93a9f5c5f15df428). If
you follow the Org-Mode path, all these operations can be done through
Magit and you may want to read [the corresponding
instructions](file:///jump_to_id/508299f7373449a3939faa5b11462bc4).
Here are other ways to learn Git through the command line:
- The [Software Carpentry git
tutorial](http://swcarpentry.github.io/git-novice/)
- The (freely available) Pro Git book ([in
English](https://git-scm.com/book/en/v2) or [in
French](https://git-scm.com/book/fr/v2)). Reading the first two
chapters is enough to get a good start.
- [Learn Git Branching](https://learngitbranching.js.org/) will allow
to interactively learn Git and to understand with branches.
Now, let's start\!
1. Obtain the repository URL
<div class="CENTER">
![](rstudio_images/adresse_depot.png)
</div>
2. Cloning the repository
``` shell
cd /the/directory/where/you/want/to/clone/your/repository
git clone https://app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git
```
Alternatively, you may want to indicate now your login although I
rather suggest you follow the *Remembering your password locally*
instructions:
``` shell
git clone https://xxx@app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git
```
Now a directory `mooc-rr` has been created on your computer.
3. Inspect the repository
``` shell
cd mooc-rr
ls # (Unix)
dir # (Windows)
```
4. Synchronizing to GitLab
You should indicate which files to track (`git add`) and commit them
locally (`git commit`) before they can be transfered (`git push`) to
GitLab. The `git status` will indicate you whether files are
tracked/modified/committed/…
Let's assume you just created a `fichier.txt` file on the top of the
`mooc-rr` directory.
``` shell
git status
```
<div class="CENTER">
![](gitlab_images/status1.png)
</div>
``` shell
git add fichier.txt
git status
```
<div class="CENTER">
![](gitlab_images/status2.png)
</div>
``` shell
git commit -m "message commit"
```
<div class="CENTER">
![](gitlab_images/commit_git.png)
</div>
``` shell
git status
```
<div class="CENTER">
![](gitlab_images/status3.png)
</div>
The file can then be transfered to GitLab:
``` shell
git push
```
At this point, git will ask you about your login/password unless you
followed the previous *Remembering your password locally*
instructions.
N.B.: you will not be allowed to propagate your modifications to
GitLab if other modifications (e.g., from someone else) have been
propagated in between
<div class="CENTER">
![](gitlab_images/rejected.png)
</div>
5. Synchronizing from Gitlab: to avoid the previous problem, you need
to fetch the remote GitLab modifications first and apply them
locally.
``` shell
git pull
```
Only then will you be able to `git push`.
module2/ressources/gitlab_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Git et GitLab
date: Thu Feb 21 18:08:21 2019
---
**Ce document est particulièrement important si vous suivez le parcours
RStudio ou Org-Mode. Vous pouvez l’ignorer dans un premier temps si**
**vous suivez le parcours Jupyter car nous avons étroitement intégré
Jupyter et GitLab dans le contexte de ce MOOC.**
Jusqu'à présent, vous avez utilisé Git uniquement via l'interface web du
GitLab que nous avons déployée pour le MOOC :
<https://app-learninglab.inria.fr/gitlab/>
Si vous accédez à ce lien depuis la plate-forme FUN, vous n'avez pas à
vous authentifier et vous pouvez facilement lire et modifier tous vos
fichiers. C'est très pratique, mais dans la plupart des cas, vous
voudrez avoir votre propre copie locale du référentiel et vous devrez
synchroniser votre copie locale avec celle de GitLab. Vous devrez
évidemment vous authentifier sur GitLab pour propager vos
modifications.
Ce document décrit le logiciel que vous devez installer sur votre
ordinateur et comment gérer l'authentification. La section
"Configuration de Git" est illustrée dans un [tutoriel
vidéo](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)
(en français).
Veuillez lire attentivement toutes ces instructions, en particulier
celle sur la "Configuration de votre mot de passe sur
GitLab".
# Table des matières <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Installer Git](#installer-git)
- [Linux (Debian, Ubuntu)](#linux-debian-ubuntu)
- [Mac OSX et Windows](#mac-osx-et-windows)
- [Configurer Git](#configurer-git)
- [Dire à Git qui vous êtes : nom et
email](#dire-à-git-qui-vous-êtes-nom-et-email)
- [Gérer les proxy](#gérer-les-proxy)
- [Récupérer votre mot de passe par défaut sur GitLab (et le
changer
éventuellement)](#récupérer-votre-mot-de-passe-par-défaut-sur-gitlab-et-le-changer-éventuellement)
- [Enregistrer votre mot de passe
localement](#enregistrer-votre-mot-de-passe-localement)
- [Optionnel : authentification par
SSH](#optionnel-authentification-par-ssh)
- [Utiliser Git par lignes de commandes pour synchroniser vos fichiers
locaux avec
Gitlab](#utiliser-git-par-lignes-de-commandes-pour-synchroniser-vos-fichiers-locaux-avec-gitlab)
# Installer Git
## Linux (Debian, Ubuntu)
Nous ne fournissons ici que des instructions pour les distributions
basées sur Debian. N'hésitez pas à contribuer à ce document en
fournissant des informations à jour sur les autres distributions
(RedHat, Fedora, par exemple).
Run (as root) :
``` bash
apt-get update ; apt-get install git
```
## Mac OSX et Windows
- Télécharger et installer Git depuis le [site
Git](https://git-scm.com/downloads).
- Clients Git optionnels (ne devraient pas être nécessaires si vous
travaillez dans RStudio) :
- [SourceTree](https://www.sourcetreeapp.com/)
- [GitHub Desktop](https://desktop.github.com/)
> Semble fonctionner avec GitLab et https (voir
> [discussion](https://github.com/desktop/desktop/issues/852)).
# Configurer Git
## Dire à Git qui vous êtes : nom et email
1. Ouvrir un terminal.
2. Définir un nom d'utilisateur et un email dans Git :
``` shell
git config --global user.name "Mona Lisa"
git config --global user.email "email@example.com"
```
3. Confirmer que vous avez correctement défini le nom d'utilisateur et
l'email Git :
``` shell
git config --global user.name
git config --global user.email
```
``` example
Mona Lisa
email@example.com
```
## Gérer les proxy
Vous êtes peut-être derrière un proxy, auquel cas vous pouvez avoir des
problèmes de clonage ou d’extraction à partir d’un dépôt distant, ou une
erreur telle que : `unable to access... Couldn't resolve host...`
Dans ce cas, envisagez quelque chose comme
ceci :
``` shell
git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port
```
Le `proxyPassword` sera stocké en texte brut (non crypté) dans votre
fichier `.gitconfig`, ce que vous ne souhaitez peut-être pas. Dans ce
cas, supprimez-le de l'URL et vous serez invité à le saisir chaque fois
que vous en aurez
besoin.
## Récupérer votre mot de passe par défaut sur GitLab (et le changer éventuellement)
**Avertissement (utilisateurs Jupyter) :** changer votre mot de passe
Gitlab par défaut vous empêchera de commiter les notebooks Jupyter que
nous avons déployés pour le MOOC. Vous devrez effectuer l’étape
supplémentaire de modification de votre `~/.git-credentials` dans
l’environnement Jupyter (éventuellement plusieurs fois).
1. Récupérer votre mot de passe par défaut en utilisant l'outil [Gitlab
credentials
retrieval](https://app-learninglab.inria.fr/jupyterhub/services/password)
comme décrit dans la [ressource
correspondante](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85).
<div class="CENTER">
![](gitlab_images/password_retrieval.png)
</div>
La première séquence de caractères longue et laide est votre
identifiant GitLab qu'il est facile de trouver une fois que vous
êtes connecté à Gitlab. Cependant la seconde séquence de caractères
est votre mot de passe et cette page Web est le seul endroit où vous
pouvez le trouver. Nous avons utilisé le mécanisme
d'authentification FUN pour propager vos informations
d'identification de sorte que seulement vous puissiez y accéder.
Vous devrez utiliser ce mot de passe lorsque vous essaierez de
propager des modifications de votre ordinateur vers GitLab.
*Note : Vous devez accéder à cette page Web à partir de la*
*plate-forme FUN, sinon vous risquez d'obtenir une erreur 405 en*
*essayant d'accéder directement à
<https://app-learninglab.inria.fr/jupyterhub/services/password>.*
<div class="CENTER">
![](gitlab_images/erreur405.png)
</div>
2. Accéder à
[GitLab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/xblock/block-v1:inria+41016+session02+type@lti+block@05a0ce425f1741e5bee5049040f70529/handler/preview_handler).
*Note : Vous devez à nouveau accéder à Gitlab à partir de la
plate-forme* *FUN, sinon vous risquez d'obtenir une erreur 405 en
essayant d'accéder directement à*
<https://app-learninglab.inria.fr/gitlab/users/sign_in/>.
3. Cliquez sur le premier bouton `Sign in`. Vous pouvez également
utiliser l'identifiant/mot de passe que vous venez de récupérer et
utiliser le second bouton `Sign in`. Le second bouton permet de plus
de se connecter sans passer par la plateforme FUN une fois que vous
connaissez votre identifiant/mot de passe.
<div class="CENTER">
![](gitlab_images/signin.png)
</div>
4. Si vous souhaitez modifier votre mot de passe, accédez à `Account >
Settings > Password` et définissez votre mot de passe à l'aide du
mot de passe par défaut que vous venez de récupérer. Encore une
fois, si vous utilisez les notebooks Jupyter que nous avons déployés
pour le MOOC, n’oubliez pas que changer votre mot de passe Gitlab
par défaut vous empêchera de les commiter. Vous devrez effectuer
l’étape supplémentaire consistant à changer votre
`~/.git-credentials` Jupyter via une console Jupyter (voir section
suivante).
<div class="CENTER">
![](gitlab_images/password.png)
</div>
## Enregistrer votre mot de passe localement
Si vous clonez votre dépôt en collant simplement l'URL de GitLab, vous
serez invité à saisir votre identifiant et votre mot de passe chaque
fois que vous souhaitez propager vos modifications locales, ce qui est
fastidieux. C’est pourquoi vous pouvez demander à Git de se rappeler de
votre identifiant et votre mot de passe comme
suit :
``` shell
git config --global credential.helper cache # remember my password
git config --global credential.helper "cache --timeout=3600" # for one hour at most
```
Avec cette configuration, vous serez invité à saisir votre mot de passe,
mais celui-ci sera mis en cache et ne sera plus demandé pendant une
heure. Vous voudrez peut-être lire [ces
instructions](https://stackoverflow.com/questions/5343068/is-there-a-way-to-skip-password-typing-when-using-https-on-github)
pour mieux comprendre comment tout cela fonctionne.
Si vous souhaitez que votre mot de passe soit mémorisé en permanence,
vous devez utiliser cette commande :
``` shell
git config credential.helper store
```
Votre mot de passe sera alors stocké dans un fichier `.git-credentials`
en texte brut (non-crypté). Sur une machine parfaitement sécurisée, cela
peut être très bien… ou pas… ;) Utilisez cette possibilité à vos risques
et périls.
## Optionnel : authentification par SSH
Il existe deux manières d'authentifier et de synchroniser votre dépôt
local avec GitLab : via HTTPS ou via SSH. Le premier est ce qui vient
d'être décrit et ne nécessite aucune installation de logiciel
particulier sur votre machine, c'est donc ce que je recommande pour ce
MOOC. Pourtant, je préfère le second (bien que cela puisse paraître un
peu plus technique), c'est pourquoi je le décris ici. Cela consiste à
installer SSH, à créer une paire de clés ou des clés privée/publique et
à télécharger votre clé publique SSH sur GitLab. Cette section fournit
des informations sur la procédure à suivre.
### Installer SSH
1. Linux (Debian, Ubuntu)
Nous ne fournissons ici que des instructions pour les distributions
basées sur Debian. N'hésitez pas à contribuer à ce document en
fournissant des informations à jour sur les autres distributions
(RedHat, Fedora, par exemple).
Run (as root) :
``` bash
apt-get update ; apt-get install openssh-client
```
2. macOS
C'est installé par défaut donc vous n'avez rien à faire.
3. Windows
Vous devez installer le client
[Putty](https://www.ssh.com/ssh/putty/windows/). Une fois
l’installation terminée, suivez la section [PuTTYgen - Key
Generator for PuTTY on
Windows](https://www.ssh.com/ssh/putty/windows/puttygen).
### Configurer SSH sur GitLab
Vous trouverez [ici](https://docs.gitlab.com/ee/ssh/) les explications
officielles sur la configuration de votre clé SSH sur GitLab. Vous
pouvez aussi regarder cette
vidéo :
<iframe width="560" height="315" src="https://www.youtube.com/embed/54mxyLo3Mqk" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
# Utiliser Git par lignes de commandes pour synchroniser vos fichiers locaux avec Gitlab
Cette section décrit un moyen générique (par lignes de commandes) de
synchroniser vos fichiers locaux avec Gitlab. Vous n'en aurez pas besoin
si vous suivez le parcours Jupyter. Si vous suivez le parcours RStudio,
toutes ces opérations peuvent être effectuées via RStudio et vous
voudrez peut-être lire [les instructions
correspondantes](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/1a4f58a1efed437c93a9f5c5f15df428).
Si vous suivez le chemin Org-Mode, toutes ces opérations peuvent être
effectuées via Magit et vous voudrez peut-être lire [les instructions
correspondantes](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/508299f7373449a3939faa5b11462bc4).
Voici d'autres moyens d'apprendre Git par lignes de commandes :
- Le [Software Carpentry git
tutorial](http://swcarpentry.github.io/git-novice/)
- Le livre Pro Git (gratuit) en
[englais](https://git-scm.com/book/en/v2) ou en
[français](https://git-scm.com/book/fr/v2). Les deux premiers
chapitres suffisent pour bien commencer.
- Le site [Apprenez Git Branching](https://learngitbranching.js.org/)
permet d'apprendre Git interactivement et de comprendre les
branches.
Maintenant, commençons \!
1. Récupérer l'URL du dépôt
<div class="CENTER">
![](rstudio_images/adresse_depot.png)
</div>
2. Cloner le dépôt
``` shell
cd /the/directory/where/you/want/to/clone/your/repository
git clone https://app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git
```
Alternativement, vous pouvez vouloir indiquer votre identifiant
maintenant, bien que je vous suggère plutôt de suivre les
instructions de la partie *Enregistrer votre mot de passe
localement*.
``` shell
git clone https://xxx@app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git
```
Maintenant un répertoire `mooc-rr` a été créé sur votre ordinateur.
3. Inspecter le répertoire correspondant au dépôt
``` shell
cd mooc-rr
ls # (Unix)
dir # (Windows)
```
4. Synchroniser avec GitLab
Vous devez indiquer les fichiers à suivre (`git add`) et les valider
localement (`git commit`) avant de pouvoir les transférer (`git
push`) à GitLab. Le `git status` vous indiquera si les fichiers sont
suivis/modifiés/commités/…
Supposons que vous venez de créer un fichier `fichier.txt` à la
racine du répertoire `mooc-rr`.
``` shell
git status
```
<div class="CENTER">
![](gitlab_images/status1.png)
</div>
``` shell
git add fichier.txt
git status
```
<div class="CENTER">
![](gitlab_images/status2.png)
</div>
``` shell
git commit -m "message commit"
```
<div class="CENTER">
![](gitlab_images/commit_git.png)
</div>
``` shell
git status
```
<div class="CENTER">
![](gitlab_images/status3.png)
</div>
Le fichier peut ensuite être transféré vers GitLab :
``` shell
git push
```
À ce stade, Git vous demandera votre identifiant/mot de passe, sauf
si vous avez suivi les instructions de la partie *Enregistrer votre
mot de passe localement*.
NB : vous ne serez pas autorisé à propager vos modifications dans
GitLab si d'autres modifications ont été propagées entre temps (par
exemple par quelqu'un d'autre).
<div class="CENTER">
![](gitlab_images/rejected.png)
</div>
5. Synchronisation à partir de Gitlab : pour éviter le problème
précédent, vous devez d’abord récupérer les modifications
distantes de GitLab et les appliquer localement.
``` shell
git pull
```
Alors seulement pourrez-vous exécuter le `git push`.
module2/ressources/jupyter.md deleted 100644 → 0
View file @ 8986dad7
---
title: Jupyter : tips and tricks, Installing and configuring
author: Arnaud Legrand, Benoit Rospars, Konrad Hinsen
date: Wed Mar 20 12:15:02 2019
---
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [1 Jupyter tips and tricks](#1-jupyter-tips-and-tricks)
- [1.1 Creating or importing a
notebook](#11-creating-or-importing-a-notebook)
- [1.2 Running R and Python in the same
notebook](#12-running-r-and-python-in-the-same-notebook)
- [1.3 Other languages](#13-other-languages)
- [2 Installing and configuring Jupyter on your
computer](#2-installing-and-configuring-jupyter-on-your-computer)
- [2.1 Installing Jupyter](#21-installing-jupyter)
- [2.2 Making sure Jupyter allows you to use
R](#22-making-sure-jupyter-allows-you-to-use-r)
- [2.3 Additional tips](#23-additional-tips)
# 1 Jupyter tips and tricks
The following
[webpage](https://www.dataquest.io/blog/jupyter-notebook-tips-tricks-shortcuts/)
lists several Jupyter tricks (in particular, it illustrates many
`IPython magic` commands) that should improve your efficiency (note that
this blog post is about two years old so some of the tricks may have
been integrated in the default behavior of Jupyter now).
## 1.1 Creating or importing a notebook
Using the Jupyter environment we deployed for this MOOC will allow to
easily access any file from your default GitLab project. There are
situations however where you may want to play with other notebooks.
- Adding a brand new notebook in a given directory
Simply follow the following steps:
1. From the menu: `File -> Open`. You're now in the Jupyter file
manager.
2. Navigate to the directory where you want your notebook to be
created.
3. Then from the top right button: `New -> Notebook: Python 3`.
4. Give your notebook a name from the menu: `File -> Rename`.
N.B.: If you create a file by doing `File -> New Notebook ->
Python 3`, the new notebook will be created in the current
directory. Moving it afterward is possible but a bit cumbersome
(you'll have to go through the Jupyter file manager by following
the menu `File -> Open`, then select it, `Shut` it `down`, and
`Move` and/or `Rename`).
- Importing an already existing notebook
If your notebook is already in your GitLab project, then simply
synchronize by using the `Git pull` button and use the `File ->
Open` menu. Otherwise, imagine, you want to import the [following
notebook](https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb)
from someone else's repository to re-execute it.
1. Download the file on your computer. E.g., for this [GitLab
hosted
notebook](https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb),
click on `Open raw` (a small `</>` within a document icon) and
save (`Ctrl-S` on most browsers) the content (a long JSON text
file).
2. Open the Jupyter file manager from the menu `File -> Open` and
navigate to the directory where you want to upload your
notebook.
3. Then from the top right button, `Upload` the previously
downloaded notebook and confirm the upload.
4. Open the freshly uploaded notebook through the Jupyter file
manager.
## 1.2 Running R and Python in the same notebook
`rpy2` package allows to use both languages in the same notebook by:
1. Loading `rpy2`:
``` python
%load_ext rpy2.ipython
```
2. Using the `%R` Ipython magic:
``` python
%%R
summary(cars)
```
Python objects can then even be passed to R as follows (assuming
`df` is a pandas dataframe):
``` python
%%R -i df
plot(df)
```
Note that this `%%R` notation indicates that R should be used for the
whole cell but an other possibility is to use `%R` to have a single line
of R within a python cell.
## 1.3 Other languages
Jupyter is not limited to Python and R. Many other languages are
available: <https://github.com/jupyter/jupyter/wiki/Jupyter-kernels>,
including non-free languages like SAS, Mathematica, Matlab… Note that
the maturity of these kernels differs widely.
None of these other languages have been deployed in the context of our
MOOC but you may want to read the next sections to learn how to set up
your own Jupyter on your computer and benefit from these extensions.
Since the question was asked several times, if you really need to stay
with SAS, you should know that SAS can be used within Jupyter using
either the [Python SASKernel](https://sassoftware.github.io/sas_kernel/)
or the [Python SASPy](https://sassoftware.github.io/saspy/) package
(step by step explanations about this are given
[here](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md)).
Since proprietary software such as SAS cannot easily be inspected, we
discourage its use as it hinders reproducibility by essence. But
perfection does not exist anyway and using Jupyter literate programming
approach allied with systematic control version and environment control
will certainly help anyway.
# 2 Installing and configuring Jupyter on your computer
In this section, we explain how to set up a Jupyter environment on your
own computer similar to the one deployed for this MOOC.
Note that Jupyter notebooks are only a small part of the picture and
that Jupyter is now part of a bigger project:
[JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906),
which allows you to mix various components (including notebooks) in your
browser. In the context of this MOOC, our time frame was too short to
benefit from JupyterLab which was still under active development. You
may, however, prefer JupyterLab when doing an installation on your own
computer.
## 2.1 Installing Jupyter
Follow these instructions if you wish to have a Jupyter environment on
your own computer similar to the one we set up for this MOOC.
First, download and install the [latest version of
Miniconda](https://conda.io/miniconda.html). We use Miniconda version
`4.5.4` and Python version `3.6` on our server.
Miniconda is a light version of Anaconda, which includes Python, the
Jupyter Notebook, and other commonly used packages for scientific
computing and data science.
Then download the [mooc<sub>rr</sub> environment
file](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57)
and create the environment using conda:
``` shell
conda env create -f environment.yml
# Windows activate the environment
activate mooc_rr
# Linux and MacOS activate the environment
source activate mooc_rr
# Linux, MacOS and Windows: launch the notebook
jupyter notebook
```
## 2.2 Making sure Jupyter allows you to use R
The environment described in the last section should include R, but if
you proceeded otherwise and only have Python available in Jupyter, you
may want to read the following
section.
### • Installing [IRKernel](https://github.com/IRkernel/IRkernel) (R package)
Do the following in R console:
Install the `devtools` package:
``` r
install.packages('devtools',dep=TRUE)
```
Define a proxy if needed:
``` r
library(httr)
set_config(use_proxy(url="proxy", port=80, username="username", password="password"))
```
Install the `IRkernel` package:
``` r
devtools::install_github('IRkernel/IRkernel')
IRkernel::installspec() # to register the kernel in the current R installation
```
### • Installing rpy2 (Python package)
On Linux, the rpy2 package is available in standard distributions
``` shell
sudo apt-get install python3-rpy2 python3-tzlocal
```
An alternative (not really recommended if the first one is available)
consists in going through the python package manager with
``` python
pip3 install rpy2
```
**Windows**
Download the `rpy2` [binary
file](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) by choosing the
right operating system.
Open a DOS console and type the following
command:
``` shell
python -m pip install rpy2‑2.9.4‑cp37‑cp37m‑win_amd64.whl # adapt filename
```
Install also `tzlocal`:
``` shell
python -m pip install tzlocal
```
## 2.3 Additional tips
### • Exporting a notebook
Here is what we had to install on a recent Debian computer to make sure
the notebook export via LaTeX works:
``` shell
sudo apt-get install texlive-xetex wkhtmltopdf
```
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
the command line with the following command:
``` bash
ipython3 nbconvert --to pdf Untitled.ipynb
```
If you want to use a specific style, then the `nbconvert` exporter
should be customized. This is discussed and demoed
[here](http://markus-beuckelmann.de/blog/customizing-nbconvert-pdf.html).
We encourage you to simply read the [doc of
nbconvert](https://nbconvert.readthedocs.io/en/latest/).
Instead of going directly through LaTeX and playing too much with the
`nbconvert` exporter, an other option consists in exporting to Markdown
and playing with [pandoc](https://pandoc.org/). Both approaches work,
it's rather a matter of taste.
**Windows**
Download and install MiKTeX from the [MiKTeX
webpage](https://miktex.org/download) by choosing the right operating
system. You will be prompted to install some specific packages when
exporting to pdf.
### • Improving notebook readability
Here are a few extensions that can ease your life:
- [Code
folding](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook)
to improve readability when browsing the notebook.
``` shell
pip3 install jupyter_contrib_nbextensions
# jupyter contrib nbextension install --user # not done yet
```
- [Hiding code](https://github.com/kirbs-/hide_code) to improve
readability when exporting.
``` bash
sudo pip3 install hide_code
sudo jupyter-nbextension install --py hide_code
jupyter-nbextension enable --py hide_code
jupyter-serverextension enable --py hide_code
```
### • Interacting with GitLab and GitHub
To ease your experience, we added pull/push buttons that allow you to
commit and sync with GitLab. This development was specific to the MOOC
but inspired from a previous [proof of
concept](https://github.com/Lab41/sunny-side-up). We have recently
discovered that someone else developed about at the same time a [rather
generic version of this Jupyter
plugin](https://github.com/sat28/githubcommit). Otherwise, remember that
it is very easy to insert a shell cell in Jupyter in which you can
easily issue git commands. This is how we work most of the time.
This being said, you may have noticed that Jupyter keeps a perfect track
of the sequence in which cells have been run by updating the "output
index". This is a very good property from the reproducibility point of
view but depending on your usage, you may find it a bit painful when
committing. Some people have thus developed [specific git
hooks](https://gist.github.com/pbugnion/ea2797393033b54674af) to ignore
these numbers when committing Jupyter notebooks. There is a long an
interesting discussion about various options on
[StackOverflow](https://stackoverflow.com/questions/18734739/using-ipython-notebooks-under-version-control).
For those who use
[JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906)
rather than the plain Jupyter, a specific [JupyterLab git
plugin](https://github.com/jupyterlab/jupyterlab-git) has been developed
to offer a nice version control experience.
module2/ressources/jupyter_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Jupyter : Trucs et astuces, installation et configuration
author: Arnaud Legrand, Benoit Rospars, Konrad Hinsen
date: Wed Mar 20 12:15:23 2019
---
# Table des matières <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [1 Jupyter: Trucs et astuces](#1-jupyter-trucs-et-astuces)
- [1.1 Création ou import d'un
notebook](#11-création-ou-import-dun-notebook)
- [1.2 Exécuter du code R et du code Python dans le même
notebook](#12-exécuter-du-code-r-et-du-code-python-dans-le-même-notebook)
- [1.3 Autres langages que Python et
R](#13-autres-langages-que-python-et-r)
- [2 Installation et configuration de Jupyter sur votre
ordinateur](#2-installation-et-configuration-de-jupyter-sur-votre-ordinateur)
- [2.1 Installation de Jupyter](#21-installation-de-jupyter)
- [2.2 S'assurer que Jupyter vous permet d'utiliser
R](#22-sassurer-que-jupyter-vous-permet-dutiliser-r)
- [2.3 Conseils additionnels](#23-conseils-additionnels)
# 1 Jupyter: Trucs et astuces
Cette [page
web](https://www.dataquest.io/blog/jupyter-notebook-tips-tricks-shortcuts/)
(en anglais) recense un certain nombre d'astuces relatives à
l'utilisation de Jupyter (et en particulier des illustrations des
nombreuses commandes magiques `IPython magic`) et susceptibles
d'améliorer votre efficacité (notez bien que ce billet a plus de deux
ans que Jupyter évoluant très rapidement, certaines de ces astuces ou de
ces modules complémentaires font maintenant partie du comportement par
défaut des versions les plus récentes de Jupyter).
## 1.1 Création ou import d'un notebook
L'environnement Jupyter que nous avons déployé dans le cadre de ce MOOC
vous permettra d'accéder très simplement à tout fichier (et en
particulier les notebooks des différents exercices que nous avons créés
pour vous) de votre projet gitlab par défaut. Il y a néanmoins des
situations où vous pouvez vouloir utiliser d'autres notebooks que ceux
du MOOC.
- Créer un notebook tout neuf dans un répertoire donné
1. À partir du menu: `File -> Open`. Ceci vous permet d'accéder au
gestionnaire de fichiers de Jupyter.
2. Naviguez jusque dans le répertoire dans lequel vous souhaitez
créer votre notebook.
3. Utilisez le bouton en haut à droite: `New -> Notebook:
Python 3`.
4. Donnez un nom à votre notebook à partir du menu: `File ->
Rename`.
N.B.: Si vous créez un notebook à partir du menu `File -> New
Notebook -> Python 3`, il sera créé dans le répertoire courant.
Le déplacer après coup et un peu pénible. Il vous faudra aller
dans le gestionnaire de fichiers de Jupyter (menu `File ->
Open`), sélectionner le notebook, l'arrêter (`Shut =down`), puis
le déplacer (`Move`) et/ou le renommer (`Rename`).
- Importer un notebook déja existant
Si le notebook qui vous intéresse est déjà dans votre projet GitLab,
il vous suffit de synchroniser la copie de votre Jupyter à l'aide du
bouton `Git
pull` et d'utiliser le menu `File -> Open`. Dans le cas contraire,
par exemple si souhaitez importer cet [autre
notebook](https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb)
rédigé par quelqu'un d'autre, procédez de la façon suivante:
1. Télé-chargez le fichier sur votre répertoire. Pour ce [Notebook
hébergé sur un
gitLab](https://app-learninglab.inria.fr/gitlab/moocrr-session1/moocrr-reproducibility-study/blob/master/src/Python3/challenger.ipynb),
cliquez sur `Open raw` (l'icone avec un petit `</>` ) et
sauvegardez (`Ctrl-S` sur la plupart des navigateurs) son
contenu (un long fichier texte au format JSON).
2. Ouvrez le gestionnaire de fichiers de Jupyter via le menu `File
->
Open` et naviguez jusqu'au répertoire où vous souhaitez déposer
votre notebook.
3. Utilisez le bouton en haut à droite `Upload` pour transférer le
document de votre ordinateur vers le serveur Jupyter et
confirmez l'upload.
4. Vous pouvez maintenant ouvrir le notebook fraîchement récupéré à
l'aide du navigateur de fichiers de Jupyter et réexécuter le
code correspondant.
## 1.2 Exécuter du code R et du code Python dans le même notebook
C'était impossible avec les premières versions de Jupyter mais c'est
désormais très facile grâce à la bibliothèque python `rpy2`. Il vous
faut tout d'abord ouvrir un notebook python.
1. Chargez la bibliothèque `rpy2`. Le `%load_ext` est une commande
magique jupyter qui charge cette bibliothèque et vous donne accès à
de nouvelles commandes magiques.
``` python
%load_ext rpy2.ipython
```
2. Utilisez la (nouvellement activée) commande magique `%R`:
``` python
%%R
summary(cars)
```
Les objets Python peuvent même être passé à R de la façon suivante
(ici, on suppose que `df` est une dataframe pandas):
``` python
%%R -i df
plot(df)
```
Cette notation `%%R` indique à Python et à Jupyter et que le langage R
doit être utilisé pour évaluer l'ensemble de la cellule. En interne,
python (`rpy2`) maintient une session R, lui passe le code de la cellule
et récupère le résultat. Jupyter fait alors le nécessaire pour
l'afficher correctement. Il est également possible d'utiliser `%R` pour
avoir une seule ligne de R au sein d'une cellule python.
## 1.3 Autres langages que Python et R
Jupyter tire son nom des langages Julia, Python, et R. Il ne se limite
donc pas aux langages Python et R. De nombreux autres langages de
programmation sont disponibles:
<https://github.com/jupyter/jupyter/wiki/Jupyter-kernels>, et en
particulier des langages non libres comme SAS, Mathematica, Matlab…
Notez que la maturité de ces noyaux est très variables.
Nous n'avons déployé aucun de ces autres langages dans le cadre du MOOC
mais nous vous invitons à lire les sections suivantes pour apprendre à
déployer votre propre instance de jupyter et activer certaines de ses
extensions.
Puisque la question est posée de façon récurrente, si vous avez besoin
d'utiliser le langage SAS plutôt que le langage R, il y a deux façons
d'utiliser SAS avec Jupyter: soit avec le noyau [Python
SASKernel](https://sassoftware.github.io/sas_kernel/), soit avec la
bibliothèque [Python SASPy](https://sassoftware.github.io/saspy/) (des
explications détaillés sont données
[ici](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md)).
Malgré la qualité et la stabilité de ce langage, SAS n'en reste pas
moins un langage propriétaire, ce qui rend l'inspection de ses
procédures très difficile et limite la réutilisation des procédures
produites par d'autres chercheurs. Nous le déconseillons donc dans un
objectif de recherche reproductible mais il faut aussi savoir ne pas
être dogmatique. La perfection n'existe pas ;) et, même en utilisant
SAS, l'utilisation de la programmation lettrée de Jupyter et d'un
contrôle de version (avec gitlab) et d'environnement (avec docker par
exemple) se révélera très certainement précieux.
# 2 Installation et configuration de Jupyter sur votre ordinateur
Dans cette section, nous expliquons comment installer, sur votre
ordinateur, un environnement Jupyter similaire à celui que nous avons
déployé pour ce MOOC.
Notez que les notebooks Jupyter ne constituent qu'une petite partie de
l'écosystème et que Jupyter fait maintenant partie d'un projet plus
large,
[JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906),
qui permet d'assembler différents composants (dont les notebooks) dans
votre navigateur. Dans le cadre de ce MOOC, nous avons manqué de temps
pour bénéficier de tout JupyterLab qui était toujours en développement
actif. À l'heure actuelle, vous pouvez cependant avoir intérêt à
installer tout JupyterLab sur votre ordinateur.
## 2.1 Installation de Jupyter
Ces instructions permettent d'obtenir sur votre ordinateur un
environnement Jupyter similaire à celui que nous avons déployé dans le
cadre du MOOC.
Téléchargez et installez la [dernière version de
Miniconda](https://conda.io/miniconda.html). Sur notre serveur, nous
utilisons la version `4.5.4` de Miniconda et la version `3.6` de Python.
Miniconda est une version légère d'Anaconda, une suite logicielle
incluant Python, Jupyter, R ainsi que les bibliothèques les plus
couramment utilisées en calcul scientifique et en science des données.
Téléchargez ensuite le [fichier d'environnement `mooc_rr`
](https://gist.github.com/brospars/4671d9013f0d99e1c961482dab533c57) et
déployez votre environnement à l'aide de conda:
``` shell
conda env create -f environment.yml
# Windows activate the environment
activate mooc_rr
# Linux and MacOS activate the environment
source activate mooc_rr
# Linux, MacOS and Windows: launch the notebook
jupyter notebook
```
## 2.2 S'assurer que Jupyter vous permet d'utiliser R
Si vous avez installé l'environnement de la façon décrite dans la
section précédente, vous devriez déjà avoir R à votre disposition et
vous n'avez donc rien à faire. Mais si vous avez procédé différemment et
n'avez que Python et Jupyter à votre disposition, il vous faudra
certainement suivre les étapes
suivantes
### • Installation de [IRKernel](https://github.com/IRkernel/IRkernel) (R package)
IRKernel vous permettra de faire des notebooks utilisant le langage R
plutôt que le langage Python. Nous supposons ici que R est déjà installé
et fonctionnel sur votre ordinateur. Dans une console R:
- Installer la bibliothèque `devtools`:
``` r
install.packages('devtools',dep=TRUE)
```
- Définissez un proxy si nécessaire (c'est important si votre
ordinateur est connecté à une entreprise qui limite l'accès à
Internet):
``` r
library(httr)
set_config(use_proxy(url="proxy", port=80, username="username", password="password"))
```
- Installez la bibliothèque `IRkernel`:
``` r
devtools::install_github('IRkernel/IRkernel')
IRkernel::installspec() # to register the kernel in the current R installation
```
### • Installation de rpy2 (Python package)
La bibliothèque `rpy2` permet à Python d'appeler R et donc de mélanger
les deux langages dans le même notebook. Cette bibliothèque est en
général disponible sur les distributions récentes. Par exemple sous
debian ou ubuntu:
``` shell
sudo apt-get install python3-rpy2 python3-tzlocal
```
Si vous ne disposez pas d'une distribution linux récente, il est
possible (mais non recommandé) d'utiliser le gestionnaire de paquets de
python:
``` python
pip3 install rpy2
```
**Windows**
Téléchargez le [fichier
binaire](https://www.lfd.uci.edu/~gohlke/pythonlibs/#rpy2) `rpy2` en
choisissant le bon système d'exploitation.
Ouvrez une console DOS et tapez les commandes
suivantes:
``` shell
python -m pip install rpy2‑2.9.4‑cp37‑cp37m‑win_amd64.whl # adapt filename
```
Installez également `tzlocal`:
``` shell
python -m pip install tzlocal
```
## 2.3 Conseils additionnels
### • Exporter un notebook
Jupyter évolue rapidement et ces informations peuvent vite devenir
obsolète mais voici ce qu'il peut être utile d'installer sur une debian
récente pour que l'export des notebooks via LaTeX soit fonctionnel:
``` shell
sudo apt-get install texlive-xetex wkhtmltopdf
```
L'export vers HTML ou PDF peut se faire dans Jupyter via le menu `File
> Download as > HTML` (ou `PDF`). Il peut également être fait en ligne
de commande de la façon suivante:
``` bash
ipython3 nbconvert --to pdf Untitled.ipynb
```
Pour utiliser un style spécifique, il suffit de personnaliser l'exporter
`nbconvert`. Cette personnalisation est présentée
[ici](http://markus-beuckelmann.de/blog/customizing-nbconvert-pdf.html)
mais nous vous encourageons à simplement lire la [documentation de
nbconvert](https://nbconvert.readthedocs.io/en/latest/).
Plutôt que de bidouiller trop `nbconvert`, il est aussi possible
d'exporter en Markdown et d'utiliser [pandoc](https://pandoc.org/) qui
est très flexible. Les deux approches sont possibles, c'est une question
de goût.
**Windows**
Nous vous conseillons de télécharger et d'installer la distribution
MiKTeX à partir du [site web de MiKTeX](https://miktex.org/download) en
choisissant le bon système d'exploitation. Lors de votre premier export
vers pdf, il vous sera certainement demandé d'installer des packages
LaTeX spécifiques.
### • Améliorer la lisibilité d'un notebook
Lorsque les notebooks s'allongent, ils deviennent vite difficile à lire.
Voici quelques extensions qui peuvent vous faciliter un peu la vie:
- Il est possible [plier/déplier votre
code](https://stackoverflow.com/questions/33159518/collapse-cell-in-jupyter-notebook):
``` shell
pip3 install jupyter_contrib_nbextensions
# jupyter contrib nbextension install --user # not done yet
```
- Il est aussi possible de [contrôler la visibilité des
cellules](https://github.com/kirbs-/hide_code), ce qui peut être
très utile si on exporte le notebook:
``` bash
sudo pip3 install hide_code
sudo jupyter-nbextension install --py hide_code
jupyter-nbextension enable --py hide_code
jupyter-serverextension enable --py hide_code
```
### • Interaction avec GitLab et GitHub
Pour rendre vous simplifier la vie, nous avons rajouté des boutons
`pull/push` dans Jupyter qui vous permettent de synchroniser vos
modifications avec GitLab. Ce développement spécifique pour ce MOOC
s'est inspiré d'une [preuve de
concept](https://github.com/Lab41/sunny-side-up) précédente mais est
vraiment *ad hoc*. Indépendemment et à peu près au même moment, une
autre personne a développé un [Plugin Jupyter assez générique permettant
de se synchroniser avec Gitlab ou
Github](https://github.com/sat28/githubcommit). Si cette fonctionnalité
vous intéresse, c'est donc une piste intéressante à explorer. Sinon,
souvenez vous qu'il est très simple d'insérer une cellule shell dans
Jupyter et dans laquelle vous pouvez facilement insérer des commandes
git. C'est la façon dont nous travaillons en pratique la majorité du
temps.
Ceci étant dit, vous avez certainement remarqué que Jupyter conserve une
trace parfaite de l'ordre dans lequel les cellules ont été exécutées en
incrémentant leur "indice". C'est une très bonne propriété d'un point de
vue reproductibilité mais il se peut, selon votre usage, que cela
s'avère peu pratique du point de vue du suivi de version. Certaines
personnes ont donc développé des [git hooks
spécifiques](https://gist.github.com/pbugnion/ea2797393033b54674af)
permettant d'ignorer ces numéros lorsque l'on committe des notebooks
Jupyter. Il y au une longue discussion à ce sujet sur
[StackOverflow](https://stackoverflow.com/questions/18734739/using-ipython-notebooks-under-version-control)
qui détaille différentes options.
Enfin, pour ceux qui utilisent
[JupyterLab](https://blog.jupyter.org/jupyterlab-is-ready-for-users-5a6f039b8906)
plutôt que le Jupyter de base, un [plugin git pour
JupyterLab](https://github.com/jupyterlab/jupyterlab-git) a été
développé et offre des fonctionnalités de suivi de version dignes d'un
IDE classique.
module2/ressources/maintaining_a_journal.md deleted 100644 → 0
View file @ 8986dad7
---
title: Maintaining a journal
date: Wed Mar 20 12:15:41 2019
---
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [1. Some examples of LabBooks provided for
inspiration](#1-some-examples-of-labbooks-provided-for-inspiration)
- [2. How to report efficiently (by Martin
Quinson)](#2-how-to-report-efficiently-by-martin-quinson)
- [Reporting](#reporting)
- [Reporting Logistics](#reporting-logistics)
- [Reporting Document
Organization](#reporting-document-organization)
# 1\. Some examples of LabBooks provided for inspiration
Since a few years, we systematically require any or our students to have
a laboratory notebook in org-mode. Most of the time, they start in
private repositories but often end up being fully opened. Here are a few
ones:
- Luka Stanisic (a former PhD student advised by Arnaud Legrand)
starting using this methodology during his Msc and developed further
throughout his PhD. Part of his [PhD
thesis](http://mescal.imag.fr/membres/luka.stanisic/thesis/thesis.pdf)
was actually about designing a methodology for reproducible
experiments in large scale distributed systems. You may want to have
a look at [his postdoc
LabBook](http://starpu-simgrid.gforge.inria.fr/) and to the [report
of Léo
Villeveygoux](https://framagit.org/lvgx/pfe/blob/master/doc/labbook.org)
whom he advised.
- Tom Cornebize is currently a PhD student advised by Arnaud Legrand
and during his MSc, he also heavily [loged his activity on
Github](https://github.com/Ezibenroc/simulating_mpi_applications_at_scale).
- [Lucas Schnorr](https://github.com/schnorr)'s students usually also
maintain their journal in a very nice way: [Tais Bellini's
BSc.](https://github.com/taisbellini/aiyra/blob/master/LabBook.org),
[Arthur Krause's
LabBook](https://github.com/mittmann/hpc/blob/master/LabBook.org),
[Luca Nesi's
LabBook](http://www.inf.ufrgs.br/~llnesi/memory_report/MemoryReport.html).
- [Martin
Quinson](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/)'s
students also follow such conventions:
- Ezequiel Torti Lopez, M2R 2014.
[Report](https://github.com/mquinson/simgrid-simpar/blob/master/report.org),
with both the data provenance and the data analysis included in
the appendix.
- Betsegaw Lemma, M2R 2017.
[LabBook](https://github.com/betsegawlemma/internship/blob/master/intern_report.org)
- Gabriel Corona, engineer on SimGrid, 2015-2016.
[Journal](https://github.com/randomstuff/simgrid-journal/blob/master/journal.org),
[Blog (findings)](http://www.gabriel.urdhr.fr/tags/simgrid/).
- Matthieu Nicolas, engineer on PLM, 2014-2016,
[Journal](https://github.com/MatthieuNICOLAS/PLM-reporting/blob/master/activity-report.org).
Org-mode is obviously not the only option and many of our students use
am mixture of org-mode, rstudio and jupyter depending on what is more
convenient.
# 2\. How to report efficiently (by Martin Quinson)
My friend Martin has gathered
\[\[<https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/>\]\[an
excellent compendium of information and references on his webpage to
explain his students what he expects from them\]\]. **I'll therefore
simply paraphrase him here** with the most important aspects related to
reporting but feel free to read [the original
version](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/):
## Reporting
I ask you to write a little reporting regularly. Depending on the
situation, it may be every day, every week or every month. In any case,
your reporting is very important for the following reasons:
- It forces you to think about what you are doing, which may help you
to unblock your problem by your own. Writing down the problems in a
clear way is often sufficient to see the solution appearing.
- It helps me following your progress even between the meetings. I
cannot unblock you if I don't detect that you are on a wrong lead or
otherwise blocked.
- It keeps a track of the steps in your work. That's good for the day
where you want to write your final report (even if a final report
should never be presented in the chronological order). That's good
for the next after you who will be supposed to continue you effort,
or to build upon it.
- That person may be yourself (if you go for a PhD program), another
intern, myself or even someone else on the Internet: that's what we
call Open Science, an effort where everyone can build upon the
scientific work of everyone.
I want you to write your reporting in an org file (yep, you don't have a
choice here). \[..\]
## Reporting Logistics
Once you're setup with all software installed and somehow configured,
you need to create a reporting file in a place where I can see it and
where it won't get lost if your disk crashes or something. Open a
dedicated git repository (on github, gitorious, gitlab, …) for that.
After your internship, your report should be archived directly in the
source tree of the software that you are working on, if any. But having
your reporting located in the source tree may complicate things during
your work.
Yes, it means that your file will be public at some point, but that's
why we call it "Open Science", after all. Also, you should write it in
English if possible. The part of your reporting that is called "Journal"
(see below) may be written in French if you are more efficient this way
but the rest must be in English. Don't make your tone too formal because
the file is public. Make it efficient. Nobody will ever blame you for
the work you did during an internship a long time ago. If you really
want, we can even make this file anonymous. Just speak to me.
You want to write your reporting before leaving work. Weekly reporting
should be written on Friday, one or two hours before leaving. That's the
best solution to have a nice week end without thinking about work, and
still lose no information that you would need on Monday morning.
## Reporting Document Organization
Your reporting document should have four main parts:
- Findings
This section summarizes the general information that you gathered
during your work. It is empty at the beginning of your internship,
and gets fleshed with the important things that you find on your
way. That's where bibliographical information go, for example. But
that's definitely not where TODO notes go (see below).
- Development
This section presents the technical sides of your work. Don't write
anything in there yet. Put it all in the Journal part for now.
- Journal
Describe the day-to-day work done for each period (day, week or
month) of your internship. That's the most important part of your
reporting, and we come back to it below.
- Conclusion
That's what you write in the next week of your internship. You can
see it as a letter to the next guy, explaining the current state of
your work, a few words about its technical organization, and what
should be done next on that topic. Keep this part highly technical,
the overall organization of your internship will be seen in your
final report.
The Journal part is the only part that you may write in French on need.
You want to add one subsection per period to your journal. Don't make it
too long, or you would waste time writing long texts that very few will
ever read. Don't make it too short or it will be impossible to
understand it on Monday morning (or three months after). Finding the
good balance is sometimes difficult, but I will provide feedback on your
first entries, so don't worry.
Each of section describing a period should contain three subsubsections:
- Things done
a few words about what you've done. Something like 2 or 4 items with
a few words describing what you've done. You can omit the title of
that section and put the items directly in the upper section (see
the example below).
- Blocking points and questions
try to explain clearly the things that block you or slow you down.
If you found the solution already, then it should be part of the
previous subsection (but you should say a few words nevertheless).
Also ask every question that you may have for me in that section. If
the question are personal (e.g., about the logistics of your
internship such as salary or so), please prefer emails that are not
publicly visible. If this section is empty for a given period, skip
it all together (no empty subsubsections).
- Planned work
A few items about what you plan to work on during the next period.
A template of reporting file is given at the end of this section. This
is just a strong advice: If you really feel better with another file
organization, then give it a try for one period, and ask for my
feedback. I can adapt, and I do not pretend that my advice is the
definitive answer. It's just the result of my experience so far.
Notice how TODO items are written: they are given as items in the
Planned work sections of the journal. As explained in the
[documentation](http://orgmode.org/manual/Checkboxes.html), you simply
have to write "\[ \]" in front of items that you plan to do in the
future.
You should add a \[1/\] on the "Planned work" line, so that emacs keeps
track of what is done and what is still to do. Once they are done, you
type C-c C-C on their lines to change the blank box \[ \] into a checked
box \[X\]. Also, the \[1/\] will be changed to denote the amount of work
that is still to be done.
At any point, you can see all ongoing TODO items with the following
keystrokes: "C-c / t". More information on TODOs in orgmode's
[documentation](http://orgmode.org/manual/TODO-basics.html). The
important thing here is that most TODO items must only be written in the
*Journal* part (so that we know when they occurred).
**Do not edit past entries of your journal**, unless you have very good
reasons. If you must, make sure that you don't lose information about
the path that you took (remember the Open Science thingy). You should
always **add** information to past entries, such
as:
``` shell
- *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information.
```
The only exception are TODO entries, that should clearly be rewritten to
DONE entries. If you need to adapt your TODO entry (because the initial
goal was poorly stated or otherwise), change the initial entry from TODO
to CANCELED (or check the box after stating in a subitem that it was not
done but canceled, and why), and create a new TODO entry in the current
period section.
``` example
* Introduction
This file contains the reporting for my beloved internship done on
this topic on that year. For now, just add the official title of
your internship (check the convention signed between your
university and my lab). After a few weeks, once you really
understand your internship, you should write a few paragraphs about
the context, problem and motivation of your work, with some
possible use cases. But don't do that right now.
* Bibliography
* Journal
** Week 2 feb
- read the doc about writing my reporting
*** Questions
- do I really have to use emacs?
*** Work Planed [1/2]
- [X] install emacs and setup orgmode
- [ ] read the provided articles
** Week 9 feb
- Installed emacs
(omit the Questions section if no question)
*** Work Planed
- do some useful work
```
module2/ressources/maintaining_a_journal_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Tenir un journal à jour
date: Wed Mar 20 12:16:07 2019
---
# Table des matières <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [1. Quelques exemples de cahiers de notes ou de laboratoires pouvant
servir de source
d'inspiration](#1-quelques-exemples-de-cahiers-de-notes-ou-de-laboratoires-pouvant-servir-de-source-dinspiration)
- [2. Comment rendre compte de son activité
efficacement](#2-comment-rendre-compte-de-son-activité-efficacement)
- [Le Reporting](#le-reporting)
- [Logistique](#logistique)
- [Organisation d'un compte rendu
d'activité](#organisation-dun-compte-rendu-dactivité)
# 1\. Quelques exemples de cahiers de notes ou de laboratoires pouvant servir de source d'inspiration
Depuis plusieurs années, nous demandons systématiquement à tout étudiant
travaillant avec nous tenir à jour un cahier de laboratoire,
généralement en org-mode. La plupart du temps, ces documents
commencent à être rédigés dans des dépôts privés mais assez souvent ils
finissent par être complètement ouverts et mis à disposition du plus
grand nombre. En voici quelques-uns:
- Luka Stanisic (un ancien doctorant d'Arnaud Legrand) a commencé à
utiliser cette méthodologie pendant son stage de M2 et a continué à
l'améliorer pendant son doctorat. Une partie de sa
[thèse](http://mescal.imag.fr/membres/luka.stanisic/thesis/thesis.pdf)
a en fait porté sur la conception d'une méthodologie adaptée à la
traçabilité et à la reproductibilité des expériences sur les
plates-formes de calcul à hautes performances. Vous pourriez donc
vouloir jeter un oeil au [cahier de laboratoire tenu pendant son
postdoc](http://starpu-simgrid.gforge.inria.fr/) ainsi qu'au
[rapport de Léo
Villeveygoux](https://framagit.org/lvgx/pfe/blob/master/doc/labbook.org)
qu'il a encadré pendant cette même période.
- Tom Cornebize est actuellement en thèse sous la supervision d'Arnaud
Legrand et comme les autres, pendant son stage de master, il a
également intensément [pris des notes sur son activité quotidienne
et les a mis à disposition sur
Github](https://github.com/Ezibenroc/simulating_mpi_applications_at_scale).
- Les étudiants de [Lucas Schnorr](https://github.com/schnorr) sont
aussi généralement bien formés à cet exercice de prise de note dans
un journal: [Tais Bellini's
BSc.](https://github.com/taisbellini/aiyra/blob/master/LabBook.org),
[Arthur Krause's
LabBook](https://github.com/mittmann/hpc/blob/master/LabBook.org),
[Luca Nesi's
LabBook](http://www.inf.ufrgs.br/~llnesi/memory_report/MemoryReport.html).
- Ceux qui travaillent sous la supervision de [Martin
Quinson](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/)
suivent des conventions similaires:
- Ezequiel Torti Lopez, pendant son M2 en 2014, a produit un
[rapport](https://github.com/mquinson/simgrid-simpar/blob/master/report.org)
où les données, leur provenance et leur analyse étaient fournies
dans l'annexe.
- Betsegaw Lemma, M2R 2017.
[LabBook](https://github.com/betsegawlemma/internship/blob/master/intern_report.org)
- Gabriel Corona (ingénieur de recherche sur le projet SimGrid,
2015-2016) maintient également un
[journal](https://github.com/randomstuff/simgrid-journal/blob/master/journal.org)
et un [blog
(findings)](http://www.gabriel.urdhr.fr/tags/simgrid/).
- Matthieu Nicolas (ingénieur sur PLM, 2014-2016):
[Journal](https://github.com/MatthieuNICOLAS/PLM-reporting/blob/master/activity-report.org).
Org-mode n'est évidemment pas la seule option et il est courant que nos
étudiants et collègues utilisent un mélange d'org-mode, rstudio et de
jupyter selon ce qui est le plus adapté à leurs besoins du moment.
# 2\. Comment rendre compte de son activité efficacement
Mon ami Martin a réalisé
\[\[<https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/>\]\[une
excellente collection d'informations et de références sur sa page web
pour expliquer à ses étudiants ce qu'il attends d'eux\]\]. **Je vais
donc tout simplement le paraphraser dans cette section** en rappelant
les éléments qui me semblent essentiels (mais je vous invite à lire
[l'original](https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/)).
## Le Reporting
Je vous demande de rendre compte de votre activité par écrit,
régulièrement. Selon la situation, cela peut être chaque jour, chaque
semaine ou chaque mois, mais dans tous les cas, votre compte rendu est
essentiel pour les raisons suivantes:
- Ça vous force à réfléchir à ce que vous êtes en train de faire, à
prendre du recul, ce qui peut vous permettre de résoudre vos
problèmes par vous même. Énoncer clairement votre problème permet
souvent de faire apparaître des solutions.
- Ça m'aide à suivre votre progression et à réfléchir à votre
problème, même entre deux réunions. Je ne pourrai pas vous aider si
je ne sais pas que vous êtes partis dans une mauvaise direction ou
même que vous êtes bloqués avec tel ou tel point technique.
- Ça vous permet de garder une trace de votre travail. C'est très
précieux le jour où vous aurez à écrire votre rapport final (même
si un rapport n'est jamais présenté dans un ordre chronologique).
- C'est aussi précieux pour celui qui viendra après vous et souhaitera
repartir de vos travaux, les poursuivre ou les améliorer. Cette
personne peut d'ailleurs être vous même dans quelques mois (si vous
vous engagez dans une thèse), un autre stagiaire, moi-même ou même
un inconnu à l'autre bout du monde et qui a trouvé vos travaux via
Internet: c'est ce qu'on appelle la science ouverte, un effort
collectif ou chacun peut efficacement s'appuyer sur le travail
scientifique de toute autre personne.
Je veux que vous écriviez votre compte rendu d'activité dans un fichier
org-mode (et oui, vous n'avez pas le choix\! ). \[..\]
## Logistique
Une fois que vous aurez mis en place et plus ou moins configuré tous les
logiciels dont vous aurez besoin, il vous faudra créer un fichier dans
un endroit auquel je puisse accéder et qui ne sera pas perdu si jamais
votre disque dur est endommagé, que vous vous faites voler votre
ordinateur, ou autre. Pour cela, commencez par créer un dépôt git (sur
github, gitorious, ou gitlab, …). À la fin de votre stage, votre rapport
devra être archivé directement dans l'arborescence du logiciel auquel
vous avez contribué. Travailler directement dans cette arborescence
pendant votre stage peut cependant être un peu compliqué.
Mais, oui, cela veut dire que votre journal sera publique à un moment ou
à un autre (après tout, c'est pour ça qu'on parle de science ouverte).
Vous avez donc intérêt à écrire votre rapport en Anglais si c'est
possible. La partie compte-rendu d'activité (votre "journal") peut être
écrite en Français si vous êtes plus efficace ainsi mais le reste doit
être rédigé en Anglais. Pas la peine de prendre un ton trop formel sous
prétexte que le document a vocation à être publique. Soyez efficace.
Personne ne vous tiendra rigueur de ce que vous avez pu écrire à
l'occasion de votre stage il y a de nombreuses années. Si vous insistez,
il est possible d'anonymiser ou de pseudonymiser ce document, venez m'en
parler.
Enfin, il est important d'écrire votre compte rendu avant de quitter
votre bureau, tant que les choses sont fraîches dans votre esprit. En
plus, cela vous libérera de la charge mentale induite par ce travail de
mémorisation. Si vous décidez de faire un reporting hebdomadaire, faites
le le vendredi, une ou deux heures avant de partir. C'est la meilleur
façon de passer un bon week-end sans avoir à penser à votre travail et
de ne perdre aucune information dont vous pourriez avoir besoin lundi
matin. Même principe si vous faites un reporting quotidien.
## Organisation d'un compte rendu d'activité
Selon moi, une bonne pratique consiste à structurer votre compte rendu
d'activité de la façon suivante:
- Résultats
Cette section résume les informations que vous avez obtenu à
l'occasion de votre recherche. Elle est généralement vide au début
de votre stage et prendra du volume au fur et à mesure que vous
trouvez des choses. C'est aussi souvent ici qu'atterrissent les
références bibliographiques par exemple mais ce n'est clairement
pas l'endroit où vous stockez votre liste des choses à faire (TODO).
- Développement
Cette section présente les aspects techniques de votre travail.
N'écrivez rien ici pour l'instant. Mettez tout ce que vous
collectez dans la partie Journal.
- Journal
C'est ici que vous décrivez votre travail au jour le jour, de façon
chronologique (jour, semaine, mois, …). C'est la partie la plus
importante de votre reporting et nous y revenons un peu plus bas.
- Conclusion
C'est la section que vous écrivez la dernière semaine (ou celle
d'après) de votre stage. Vous pouvez la voir comme une lettre à la
prochaine personne expliquant l'état actuel de votre travail, avec
quelques informations que son organisation technique et ce qui,
selon vous, sont les prochaines choses à faire et pourquoi. Cette
partie peut-être hautement technique, les tenants et les
aboutissants plus globaux de votre stage étant des considérations
qui apparaîtront plutôt dans votre rapport final de stage.
La partie Journal est la seul que vous avez le droit d'écrire en
Français si vous êtes plus à l'aise ainsi. Pas la peine de vous
"répandre", vous perdriez votre temps à écrire un long texte que très
peu de personnes seront susceptibles de lire. Ne la bâclez pour autant
car si elle est trop courte elle sera incompréhensible la semaine
d'après (ou trois mois plus tard). Trouver le bon équilibre n'est pas
toujours simple mais je vous ferai un retour sur vos premières entrées
donc ne vous inquiétez pas.
Une bonne habitude consiste à ce que chacune des entrées section
décrivant une période de travail soit structurée de la façon suivante:
- Travail effectué
quelques mots sur ce que vous avez fait et son contexte. Cela peut
prendre la forme d'une petite liste de 2 à 4 entrées sur ce que vous
avez fait et pourquoi vous l'avez fait.
- Ponts bloquants et questions
essayez d'expliquer clairement les points de blocage que vous
rencontrez ou bien les points qui vous gênent et vous ralentissent.
Si vous avez finalement déjà trouvé la réponse à ces problèmes,
indiquez leu dans la sous-section précédente. C'est aussi ici que
vous écrirez toute question que vous aimeriez me poser. Si ce sont
des interrogations personnelles (par exemple sur la logistique de
votre stage, le logement, votre salaire), utilisez plutôt le mail
qui restera privé entre nous (souvenez vous que ce journal a
vocation a devenir un document publique). Si cette section est vide
pour une période donnée, sautez la tout simplement (ne gardez pas de
sous-sections vides).
- Travaux prévus
Une petite liste détaillant les points auxquels vous comptez vous
attaquer dans la période à venir.
Vous trouverez à la fin un modèle de compte rendu d'activité. Un
conseil: si vraiment vous vous sentez mieux avec une autre structuration
de document, essayez pour une période donnée et on fera le point. Je
sais m'adapter et je ne prétends pas avoir la science infuse ni que mes
conseils soient la solution ultime et universelle. C'est juste le
résultat de mon expérience jusqu'ici.
Remarquez comment les entrées commençant par le mot-clé TODO
apparaissent. On le retrouvera typiquement dans les sections "Travaux
prévus" du journal. Comme expliqué dans la [documentation
d'org-mode](http://orgmode.org/manual/Checkboxes.html), vous pouvez
aussi tout simplement écrire `[ ]` au début de chaque élément d'une
liste de choses que vous avez l'intention de faire.
Dans ce cas, en rajoutant un \[1/\] à la fin de la sous-sous-section
"Travaux prévus", Emacs tiendra à jour le compte des choses faites et
qui restent à faire. Une fois que ce qui est décrit dans l'un des
éléments d'une liste est faite, il vous suffit de faire `C-c C-C` sur
cette entrée pour transformer le `[ ]` en une version cochée `[X]`. Le
\[1/\] sera alors mis à jour pour refléter la quantité de travail
restant. Lorsque tout aura été effectué, le mot-clé TODO passera à DONE,
ce qui procure un incroyable sentiment de satisfaction. :)
À tout moment, vous pouvez avoir accès à l'ensemble des choses à faire
(TODO) à l'aide du raccourci clavier suivant: `C-c / t`. Vous trouverez
plus d'informations sur les TODOs dans la [documentation
d'orgmode](http://orgmode.org/manual/TODO-basics.html). Le point
important à retenir ici est que la plupart des TODO doivent apparaître
dans la partie journal (afin de savoir quand ils se sont posés).
**N'éditez jamais les entrées de votre journal a posteriori**, sauf si
vous avez vraiment une très bonne raison. Si cela devait arriver,
assurez vous que vous ne perdez pas d'informations sur ce que vous avez
fait et les choix que vous avez effectués (souvenez vous, science
ouverte, tout ça tout ça). Il faut toujours **ajouter** des nouvelles
informations aux anciennes, par exemple comme
ceci:
``` shell
- *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information.
```
La seule exception à cet édition des entrées passées, ce sont les
entrées de type TODO, qui sont dynamiques et ont vocation à être
transformées en entrées de type DONE. Si vous réalisez qu'il est utile
d'adapter une entrée TODO (parce que l'objectif initial a été mal
formulé, est inadapté, que sais je?), faites passer l'entrée d'origine
de TODO à CANCELED (et/ou cochez le `[ ]` en indiquant dans une
sous-entrée que cette tâche n'a pas été faite mais annulée et pourquoi)
et créez une nouvelle entrée TODO dans la section du jour.
``` example
* Introduction
This file contains the reporting for my beloved internship done on
this topic on that year. For now, just add the official title of
your internship (check the convention signed between your
university and my lab). After a few weeks, once you really
understand your internship, you should write a few paragraphs about
the context, problem and motivation of your work, with some
possible use cases. But don't do that right now.
* Bibliography
* Journal
** Week 2 feb
- read the doc about writing my reporting
*** Questions
- do I really have to use emacs?
*** Work Planed [1/2]
- [X] install emacs and setup orgmode
- [ ] read the provided articles
** Week 9 feb
- Installed emacs
(omit the Questions section if no question)
*** Work Planed
- do some useful work
```
module2/ressources/orgmode_examples/README.md deleted 100644 → 0
View file @ 8986dad7
---
title: Document Examples
author: Arnaud Legrand
date: Wed Mar 20 13:03:17 2019
---
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Examples from the Video](#examples-from-the-video)
- [Other examples](#other-examples)
# Examples from the Video
In the MOOC video, I quickly demo how org-mode can be used in various
contexts. Here are the (sometimes trimmed) corresponding org-files.
These documents depend on many other external data files and are not
meant to lead to reproducible documents but it will give you an idea of
how it can be organized:
1. [journal.org](journal.org): an excerpt (I've only left a few code
samples and links to some resources on R, Stats, …) from my own
journal. This is a personal document where everything (meeting
notes, hacking, random thoughts, …) goes by default. Entries are
created with the `C-c c` shortcut.
2. [labbook<sub>single</sub>.org](labbook_single.org): this is an
excerpt from the laboratory notebook [Tom
Cornebize](https://cornebize.net/) wrote during his Master thesis
internship under my supervision. This a personal labbook. I consider
this notebook to be excellent and was the ideal level of details for
us to communicate without any ambiguity and for him to move forward
with confidence.
3. [paper.org](paper.org): this is an ongoing paper based on the
previous labbook of Tom Cornebize. As such it is not reproducible as
there are hardcoded paths and uncleaned dependencies but writing it
from the labbook was super easy as we just had to cut and paste the
parts we needed. What may be interesting is the organization and the
org tricks to export to the right LaTeX style. As you may notice, in
the end of the document, there is a commented section with emacs
commands that are automatically executed when opening the file. It
is an effective way to depend less on the `.emacs/init.el` which is
generally customized by everyone.
4. [labbook<sub>several</sub>.org](labbook_several.org): this is a
labbook for a specific project shared by several persons. As a
consequence it starts with information about installation, common
scripts, has section with notes about all our meetings, a section
with information about experiments and an other one about analysis.
Entries could have been labeled by who wrote them but there were
only a few of us and this information was available in git so we did
not bother. In such labbook, it is common to find annotations
indicating that such experiment was `:FLAWED:` as it had some
issues.
5. [technical<sub>report</sub>.org](technical_report.org): this is a
short technical document I wrote after a colleague sent me a PDF
describing an experiment he was conducting and asked me about how
reproducible I felt it was. It turned out I had to cut and paste the
C code from the PDF, then remove all the line numbers and fix
syntax, etc. Obviously I got quite different performance results but
writing everything in org-mode made it very easy to generate both
HTML and PDF and to explicitly explain how the measurements were
done.
# Other examples
Here are a few links to other kind of examples:
- Slides: all my slides for a series of lectures is available here:
<https://github.com/alegrand/SMPE>. Here is a [typical
source](https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.org)
and the [resulting
PDF](https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.pdf)
- Lucas Schnorr, a colleague, maintains:
- a set of templates for various computer science
journals/conferences:
[IEEE](https://github.com/schnorr/ieeeorg),
[Wiley](https://github.com/schnorr/wileyorg),
[ACM](https://github.com/schnorr/acmorg),
[LNCS](https://github.com/schnorr/llncsorg)
- his lecture on programming languages for undergrads:
<https://github.com/schnorr/mlp/tree/master/conteudo>
- John Kitchin is an expert org-mode user and he maintains a very
interesting [blog with many interesting
tips](http://kitchingroup.cheme.cmu.edu/blog/). You may want to
check this [seminar he gave at
SciPy](https://www.youtube.com/watch?v=IsSMs-4GlT8&list=FLQp2VLAOlvq142YN3JO3y8w&app=desktop).
module2/ressources/orgmode_examples/README_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Quelques exemples de documents en Org-Mode
author: Arnaud Legrand
date: Wed Mar 20 13:01:44 2019
---
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [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) correspondant. Ces documents dépendent souvent d'autres 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. [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`.
2. [labbook<sub>single</sub>.org](labbook_single.org): ceci est un
extrait du cahier de laboratoire tenu par [Tom
Cornebize](https://cornebize.net/) pendant son stage de Master sous
ma direction. C'est un cahier de laboratoire personnel et 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.
3. [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.
4. [labbook<sub>several</sub>.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.
5. [technical<sub>report</sub>.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.
# 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 [blog avec une
foule d'astuces
intéressantes](http://kitchingroup.cheme.cmu.edu/blog/). Vous
pourriez vouloir jeter un œil au [séminaire qu'il a donné à
SciPy](https://www.youtube.com/watch?v=IsSMs-4GlT8&list=FLQp2VLAOlvq142YN3JO3y8w&app=desktop).
- 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
[sources](https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.org)
avec le [PDF
résultant](https://raw.githubusercontent.com/alegrand/SMPE/master/lectures/lecture_central_limit_theorem.pdf).
- Lucas Schnorr, un collègue et ami, maintient:
- un ensemble de modèles en org-mode pour certaines conférences et
journaux en informatique:
[IEEE](https://github.com/schnorr/ieeeorg),
[Wiley](https://github.com/schnorr/wileyorg),
[ACM](https://github.com/schnorr/acmorg),
[LNCS](https://github.com/schnorr/llncsorg)
- son cours de programmation (en portugais) pour les élèves de
licence: <https://github.com/schnorr/mlp/tree/master/conteudo>
module2/ressources/rstudio.md deleted 100644 → 0
View file @ 8986dad7
---
title: Rstudio
date: Tue Feb 19 19:19:03 2019
---
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Installing RStudio](#installing-rstudio)
- [Linux (debian, ubuntu)](#linux-debian-ubuntu)
- [Mac OSX and Windows](#mac-osx-and-windows)
- [RStudio documentation](#rstudio-documentation)
- [Using Git from RStudio](#using-git-from-rstudio)
- [Cloning a repository](#cloning-a-repository)
- [Modifying a file](#modifying-a-file)
# 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., RedHat, Fedora).
Today, the stable versions of the most common distributions provide
recent enough versions of R:
- Debian (stretch) ships with
[R 3.3.3-1](https://packages.debian.org/stretch/r-base),
[knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr),
and
[ggplot 2.2.1](https://packages.debian.org/stretch/r-cran-ggplot2)
- Ubuntu (bionic 18.04) ships with
[R 3.4.4](https://packages.ubuntu.com/bionic/r-base), and
[knitr 1.17](https://packages.ubuntu.com/bionic/r-cran-knitr), and
[ggplot 2.2.1](https://packages.ubuntu.com/bionic/r-cran-ggplot2)
- Ubuntu (artful 17.04) ships with
[R 3.4.2](https://packages.ubuntu.com/artful/r-base), and
[knitr 1.15](https://packages.ubuntu.com/artful/r-cran-knitr), and
[ggplot 2.2.1](https://packages.ubuntu.com/artful/r-cran-ggplot2)
If your distribution is older than this, well, it may be a good time for
upgrading…
### Installing R
First, you need to install the R language and convenient packages by
running (as
root):
``` shell
apt-get update ; sudo apt-get install r-base r-cran-knitr r-cran-ggplot2
```
Alternatively, if the installation of `r-cran-gplot2` or `r-cran-knitr`
fails, you may want to install them locally (through the R packaging
system) and manually by running the following commands in R (or
RStudio):
``` r
install.packages("knitr")
install.packages("ggplot2")
```
If you plan to export pdf documents with LaTeX, you probably also want
to run (as root):
``` bash
apt-get update ; apt-get install texlive-base
```
### Installing RStudio
RStudio is unfortunately not packaged within Debian so the easiest is to
download the corresponding Debian package on the [RStudio
webpage](https://www.rstudio.com/products/rstudio/download/#download)
and then to install it manually (you may have to adjust the version
number in the following example). Here is how to install it:
``` shell
cd /tmp/
wget https://download1.rstudio.org/rstudio-xenial-1.1.453-amd64.deb
sudo dpkg -i rstudio-xenial-1.1.453-amd64.deb
sudo apt-get update ; sudo apt-get -f install # to fix possibly missing dependencies
```
## Mac OSX and Windows
> Some instructions on installing R and knitr must be missing. This
> should be tested and improved.
- Download and install R from the [CRAN
webpage](https://cran.r-project.org/) by choosing the right
operating system.
- Download and install RStudio from the [RStudio
webpage](https://www.rstudio.com/products/rstudio/download/#download)
by choosing the right operating system.
- Download and install MiKTeX from the [MiKTeX
webpage](https://miktex.org/download) by choosing the right
operating system. You will be prompted to install some specific
packages when exporting to pdf.
- Open RStudio and type the following commands in the console to
install `knitr` and `ggplot2`:
<!-- end list -->
``` r
install.packages("knitr", dep=TRUE)
install.packages("ggplot2", dep=TRUE)
```
# RStudio documentation
The RStudio team has created a lot of very good material and tutorials.
You should definitively look at the [Cheat sheets
webpage](https://www.rstudio.com/resources/cheatsheets/). In particular
you may want to have look at the following ones:
- [The RStudio
IDE](https://github.com/rstudio/cheatsheets/raw/master/rstudio-ide.pdf),
- [R
Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf)
(here is also a [nice step-by-step presentation of
Rmarkdown](https://rmarkdown.rstudio.com/)),
- The [R Markdown Reference
guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf),
- [Data visualization with
ggplot2](https://github.com/rstudio/cheatsheets/raw/master/data-visualization-2.1.pdf),
- [Data transformation with
dplyr](https://github.com/rstudio/cheatsheets/raw/master/data-transformation.pdf)
In case it helps, here are some (sometimes outdated) French versions of
these documents:
- [L'IDE
RStudio](https://github.com/rstudio/cheatsheets/raw/master/translations/french/rstudio-IDE-cheatsheet.pdf)
- [Visualisation de données avec
ggplot2](https://github.com/rstudio/cheatsheets/raw/master/translations/french/ggplot2-french-cheatsheet.pdf)
- [Transformation de données avec
dplyr](https://github.com/rstudio/cheatsheets/raw/master/translations/french/data-wrangling-french.pdf)
- [Un court document sur R
Markdown](https://www.fun-mooc.fr/c4x/UPSUD/42001S02/asset/RMarkdown.pdf)
# Using Git from RStudio
If you have never used git with RStudio, **we strongly advise that you
follow [our tutorial on using git from
RStudio](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/d132a854b0464ad29085cedaded23136)**
(*"RStudio et Gitlab"* in French). Before proceeding, make sure you also
have followed the **["git/GitLab configuration"
tutorial](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)**
(in French).
Alternatively, you may want to watch [this
video](https://www.youtube.com/embed/uHYcDQDbMY8) (in English). If you
do not like videos, you should have a look at the [step-by-step
explanations from Software
Carpentry](https://swcarpentry.github.io/git-novice/14-supplemental-rstudio/index.html).
It comes with many screenshots and is quite progressive.
## Cloning a repository
Open RStudio and do the following steps:
- Create a new version controled project: `File / New Project /
Version Control`
<div class="CENTER">
![](rstudio_images/new_project.png)
![](rstudio_images/git.png)
</div>
- Get the URL from your GitLab repository:
<div class="CENTER">
![](rstudio_images/adresse_depot.png)
</div>
- Indicate this URL in the "Repository URL" field (*you may want to
prefix this URL with `xxx@` where `xxx` is* *your Gitlab id to avoid
repeatedly giving it later on*).
<div class="CENTER">
![](rstudio_images/clone.png)
</div>
- If you're behind a proxy, git should be configured accordingly.
Check the ["Dealing with proxies"
section](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85).
- Git will then connect to Gitlab and fetch a whole copy of the
repository.
- RStudio should restart in a mode related to Git:
<div class="CENTER">
![](rstudio_images/rstudio.png)
</div>
- The file manager on the right, allows you to browse the version
controled repository.
## Modifying a file
- Open `Module2/exo1/toy_document.Rmd` and perform a simple
modification.
- Save
- Go to the Git menu to commit
<div class="CENTER">
![](rstudio_images/commit.png)
![](rstudio_images/commit2.png)
</div>
- Select the lines to commit and then click on `commit`
<div class="CENTER">
![](rstudio_images/commit5.png)
</div>
Your modifications have now been commited on your local machine.
They haven't been propagated to GitLab yet.
- Click on `push` to propagate them on GitLab
<div class="CENTER">
![](rstudio_images/push.png)
![](rstudio_images/push2.png)
![](rstudio_images/push3.png)
</div>
**NB**: You won't be able to propagate your modifications on GitLab
if some modifications have been done on GitLab in the meantime.
![](rstudio_images/push4.png)
- You should first merge these remote modifications locally. Click on
`pull` to get these modifications on your machine.
module2/ressources/rstudio_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Rstudio
date: Tue Feb 19 19:19:03 2019
---
# Table des matières <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Installer RStudio](#installer-rstudio)
- [Linux (debian, ubuntu)](#linux-debian-ubuntu)
- [Mac OSX and Windows](#mac-osx-and-windows)
- [Documentation RStudio](#documentation-rstudio)
- [Utiliser Git avec RStudio](#utiliser-git-avec-rstudio)
- [Cloner un dépôt](#cloner-un-dépôt)
- [Modifier un fichier](#modifier-un-fichier)
# Installer RStudio
## Linux (debian, ubuntu)
Nous ne fournissons ici que des instructions pour les distributions
basées sur Debian. N’hésitez pas à contribuer à ce document en
fournissant des informations à jour sur les autres distributions
(RedHat, Fedora, par exemple).
Aujourd'hui, les versions stables des distributions les plus courantes
fournissent des versions assez récentes de R :
- Debian (stretch) est livré avec
[R 3.3.3-1](https://packages.debian.org/stretch/r-base),
[knitr 1.15.1](https://packages.debian.org/stretch/r-cran-knitr), et
[ggplot 2.2.1](https://packages.debian.org/stretch/r-cran-ggplot2)
- Ubuntu (bionic 18.04) est livré avec
[R 3.4.4](https://packages.ubuntu.com/bionic/r-base),
[knitr 1.17](https://packages.ubuntu.com/bionic/r-cran-knitr), et
[ggplot 2.2.1](https://packages.ubuntu.com/bionic/r-cran-ggplot2)
- Ubuntu (artful 17.04) est livré avec
[R 3.4.2](https://packages.ubuntu.com/artful/r-base),
[knitr 1.15](https://packages.ubuntu.com/artful/r-cran-knitr), et
[ggplot 2.2.1](https://packages.ubuntu.com/artful/r-cran-ggplot2)
Si votre distribution est plus ancienne, c'est peut-être l'occasion de
la mettre à jour…
### Installer R
Pour commencer, vous devez installer le langage R et quelques packages
en exécutant (à la
racine) :
``` shell
apt-get update ; sudo apt-get install r-base r-cran-knitr r-cran-ggplot2
```
Si l'installation de `r-cran-knitr` ou `r-cran-gplot2` échoue, vous
pouvez également installer ces packages manuellement en exécutant les
commandes suivantes sous R (ou RStudio) :
``` r
install.packages("knitr")
install.packages("ggplot2")
```
Si vous envisagez d'exporter des documents pdf avec LaTeX, il faudra
probablement aussi exécuter (à la racine) :
``` shell
apt-get update ; apt-get install texlive-base
```
### Installer RStudio
RStudio n’est malheureusement pas intégré à Debian. Le plus simple est
de télécharger le paquet Debian correspondant sur le [site
RStudio](https://www.rstudio.com/products/rstudio/download/#download),
puis de l’installer manuellement (vous devrez peut-être adapter le
numéro de version) :
``` shell
cd /tmp/
wget https://download1.rstudio.org/rstudio-xenial-1.1.453-amd64.deb
sudo dpkg -i rstudio-xenial-1.1.453-amd64.deb
sudo apt-get update ; sudo apt-get -f install # to fix possibly missing dependencies
```
## Mac OSX and Windows
- Télécharger et installer R depuis le [site
CRAN](https://cran.r-project.org/) en choisissant le bon système
d'exploitation.
- Télécharger et installer RStudio depuis le [site
RStudio](https://www.rstudio.com/products/rstudio/download/#download)
en choisissant le bon système d'exploitation.
- Télécharger et installer MiKTeX depuis le [site
MiKTeX](https://miktex.org/download) en choisissant le bon système
d'exploitation. Vous serez amené à installer différents packages
lors du premier export pdf.
- Ouvrir RStudio et exécuter les commandes suivantes dans la console
pour installer `knitr` et `ggplot2`
<!-- end list -->
``` r
install.packages("knitr", dep=TRUE)
install.packages("ggplot2", dep=TRUE)
```
# Documentation RStudio
L’équipe de RStudio a créé différents matériels et tutoriels très bien
faits. Nous vous recommandons de consulter les [fiches
mémo](https://www.rstudio.com/resources/cheatsheets/). En particulier,
vous pourriez être intéressés par celles-ci :
- [RStudio
IDE](https://github.com/rstudio/cheatsheets/raw/master/rstudio-ide.pdf),
- [R
Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf)
(here is also a [nice step-by-step presentation of
Rmarkdown](https://rmarkdown.rstudio.com/)),
- The [R Markdown Reference
guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf),
- [Data visualization with
ggplot2](https://github.com/rstudio/cheatsheets/raw/master/data-visualization-2.1.pdf),
- [Data transformation with
dplyr](https://github.com/rstudio/cheatsheets/raw/master/data-transformation.pdf)
Voici aussi les versions françaises de certains documents mais elles ne
sont pas toujours à jour :
- [IDE
RStudio](https://github.com/rstudio/cheatsheets/raw/master/translations/french/rstudio-IDE-cheatsheet.pdf)
- [Visualisation de données avec
ggplot2](https://github.com/rstudio/cheatsheets/raw/master/translations/french/ggplot2-french-cheatsheet.pdf)
- [Transformation de données avec
dplyr](https://github.com/rstudio/cheatsheets/raw/master/translations/french/data-wrangling-french.pdf)
- [Un court document sur R
Markdown](https://www.fun-mooc.fr/c4x/UPSUD/42001S02/asset/RMarkdown.pdf)
# Utiliser Git avec RStudio
La première chose à faire est de configurer Git sur votre ordinateur.
Pour ce faire, vous pouvez suivre la vidéo [configurer Git pour
Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)
(en français) et le document [Git et
Gitlab](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/module2/ressources/gitlab_fr.org)
correspondant (en français).
Vous pourrez alors utiliser Git avec RStudio. Pour ce faire, vous pouvez
suivre la vidéo [RStudio -
Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/d132a854b0464ad29085cedaded23136)
(en français) dont les étapes sont reprises ci-dessous.
*(Nous vous signalons aussi cette*
[vidéo](https://www.youtube.com/embed/uHYcDQDbMY8) *(en anglais) ainsi
que le* [tuto pas à
pas](https://swcarpentry.github.io/git-novice/14-supplemental-rstudio/index.html)
*(en anglais) de Software Carpentry.)*
## Cloner un dépôt
Ouvrir RStudio et procéder comme suit :
- Créer un nouveau projet sous contrôle de version : `File / New
Project / Version Control`
<div class="CENTER">
![](rstudio_images/new_project.png)
![](rstudio_images/git.png)
</div>
- Récupérer l'URL du dépôt Gitlab
<div class="CENTER">
![](rstudio_images/adresse_depot.png)
</div>
- Indiquez cette URL dans le champ "Repository URL" *(vous voudrez*
*peut-être préfixer cette URL avec `xxx@` où `xxx` est votre
identifiant* *Gitlab pour éviter d'avoir à le ressaisir
ultérieurement)*.
<div class="CENTER">
![](rstudio_images/clone.png)
</div>
- Si vous êtes derrière un proxy, il faut le définir dans Git (voir le
paragraphe "Gérer les proxy" de la page sur [Git et
Gitlab](https://www.fun-mooc.fr/courses/course-v1:inria+41016+session02/jump_to_id/7508aece244548349424dfd61ee3ba85)).
- Git se connecte à Gitlab et récupère une copie complète du dépôt.
- RStudio redémarre dans un mode lié à Git :
<div class="CENTER">
![](rstudio_images/rstudio.png)
</div>
- Le gestionnaire de fichiers à droite vous permet de parcourir le
dépôt sous contrôle de version.
## Modifier un fichier
- Ouvrir le fichier `Module2/exo1/toy_document.Rmd` et le modifier.
- Enregistrer.
- Aller dans le menu Git pour effectuer le commit.
<div class="CENTER">
![](rstudio_images/commit.png)
![](rstudio_images/commit2.png)
</div>
- Sélectionner les lignes à commiter puis cliquer sur `commit`.
<div class="CENTER">
![](rstudio_images/commit5.png)
</div>
Les modifications ont été commitées uniquement sur la machine. Elles
n'ont pas été propagées sur Gitlab.
- Cliquer sur `push` pour les propager sur Gitlab.
<div class="CENTER">
![](rstudio_images/push.png)
![](rstudio_images/push2.png)
![](rstudio_images/push3.png)
</div>
**NB :** Vous ne pouvez pas propager vos modifications sur GitLab si
des modifications ont été faites sur GitLab entre-temps.
<div class="CENTER">
![](rstudio_images/push4.png)
</div>
- Il faut d’abord récupérer ces modifications distantes sur votre
machine locale. Pour ce faire cliquer sur `pull`.
module2/slides/ressources.md deleted 100644 → 0
View file @ 8986dad7
---
title: Computational Documents
date: Wed Mar 20 13:19:19 2019
---
This document gathers most references mentioned in the videos. This is a
rather crude
list.
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [M2-S0: Computational Documents](#m2-s0-computational-documents)
- [M2-S1: A few Recent Controversial
Studies](#m2-s1-a-few-recent-controversial-studies)
- [Economy: Austerity in Fiscal
Policy](#economy-austerity-in-fiscal-policy)
- [Functional MRI](#functional-mri)
- [Incorrect Protein Structures](#incorrect-protein-structures)
- [Other domains](#other-domains)
- [M2-S2: Why is This so Difficult?](#m2-s2-why-is-this-so-difficult)
- [Mistakes](#mistakes)
- [Going Public?](#going-public)
- [M2-S3: Computational Documents:
Principles](#m2-s3-computational-documents-principles)
- [M2-S5: Collaborating](#m2-s5-collaborating)
- [Preparing a Document for a Journal or a
Conference](#preparing-a-document-for-a-journal-or-a-conference)
- [M2-S6: Comparative Study](#m2-s6-comparative-study)
- [Exemples of Org-Mode
documents](#exemples-of-org-mode-documents)
# M2-S0: Computational Documents
# M2-S1: A few Recent Controversial Studies
## Economy: Austerity in Fiscal Policy
- [Reinhart et
Rogoff](https://en.wikipedia.org/wiki/Growth_in_a_Time_of_Debt):
*Growth in a Time of Debt*
- Herndon, Ash et Pollin
- Wray: combining data across centuries, exchange rate regimes,
## Functional MRI
- 2010: [Bennett et al. and the dead
salmon](https://www.researchgate.net/publication/255651552_Neural_correlates_of_interspecies_perspective_taking_in_the_post-mortem_Atlantic_Salmon_an_argument_for_multiple_comparisons_correction)
☺
- 2016: [Eklund, Nichols, and
Knutsson](http://www.pnas.org/content/113/28/7900.abstract). [A bug
in fmri software could invalidate 15 years of brain
research](http://www.sciencealert.com/a-bug-in-fmri-software-could-invalidate-decades-of-brain-research-scientists-discover)
(*40 000 articles*)
- 2016: But it's [more subtle than it looks
like](https://www.cogneurosociety.org/debunking-the-myth-that-fmri-studies-are-invalid/).
[Nichols](http://blogs.warwick.ac.uk/nichols/entry/bibliometrics_of_cluster/).
*≈ 3 600 impacted studies*
## Incorrect Protein Structures
[A "buggy
software"](https://people.ligo-wa.caltech.edu/~michael.landry/calibration/S5/getsignright.pdf).
## Other domains
- [Oncology](http://www.nature.com/nrd/journal/v10/n9/full/nrd3439-c1.html?foxtrotcallback=true):
"*half of published studies, even in prestigious journals, can't be
reproduced in industrial
labs*"
- [Psychology](http://theconversation.com/we-found-only-one-third-of-published-psychology-research-is-reliable-now-what-46596):
"*attempting to reproduce 100 previously published findings*, *only
one-third of published psychology research was found to be
reliable*"
# M2-S2: Why is This so Difficult?
## Mistakes
- [Computers broke
science](http://theconversation.com/how-computers-broke-science-and-what-we-can-do-to-fix-it-49938)
- [Programming and data manipulation mistakes in
Genomics](https://qz.com/768334/years-of-genomics-research-is-riddled-with-errors-thanks-to-a-bunch-of-botched-excel-spreadsheets/)
## Going Public?
- Someone may [benefit from my hard
work](http://www.nature.com/news/the-top-100-papers-1.16224)
# M2-S3: Computational Documents: Principles
# M2-S5: Collaborating
## Preparing a Document for a Journal or a Conference
Requirements for producing a **pdf**:
- Internally, *pandoc*, *knitr* or *emacs/org-mode*
- *LaTeX* should be installed
- <http://blog.juliusschulz.de/blog/ultimate-ipython-notebook>
- <https://github.com/kirbs-/hide_code> is a
must-have
- <http://svmiller.com/blog/2016/02/svm-r-markdown-manuscript/>
- <https://github.com/balouf/Kleinberg/blob/master/KleinbergsGridSimulator.ipynb>
# M2-S6: Comparative Study
## [Exemples of Org-Mode documents](../ressources/orgmode_examples/README.org)
module2/slides/ressources_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Le document computationnel
date: Wed Mar 20 13:19:19 2019
---
Ce document rassemble la plupart des références mentionnées dans les
vidéos. C'est une liste relativement grossière qui mériterait d'être
améliorée.
# Table des matières <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [M2-S0: Le document
computationnel](#m2-s0-le-document-computationnel)
- [M2-S1: Exemples récents d'études assez
discutées](#m2-s1-exemples-récents-détudes-assez-discutées)
- [Économie: Politiques
d'austérité](#économie-politiques-daustérité)
- [Les IRM fonctionnelles](#les-irm-fonctionnelles)
- [Les fausses structures de
protéines](#les-fausses-structures-de-protéines)
- [Autres domaines](#autres-domaines)
- [M2-S2: Pourquoi est-ce
difficile?](#m2-s2-pourquoi-est-ce-difficile)
- [Les erreurs classiques](#les-erreurs-classiques)
- [Tout rendre publique ?](#tout-rendre-publique)
- [M2-S3: Le document computationnel :
principe](#m2-s3-le-document-computationnel-principe)
- [M2-S5: Travailler avec les
autres](#m2-s5-travailler-avec-les-autres)
- [Préparation d'un document pour un journal ou pour une
conférence](#préparation-dun-document-pour-un-journal-ou-pour-une-conférence)
- [M2-S6: Analyse comparée des différents
outils](#m2-s6-analyse-comparée-des-différents-outils)
- [Exemples de document Org-Mode](#exemples-de-document-org-mode)
# M2-S0: Le document computationnel
# M2-S1: Exemples récents d'études assez discutées
## Économie: Politiques d'austérité
- [Reinhart et
Rogoff](https://en.wikipedia.org/wiki/Growth_in_a_Time_of_Debt):
*Growth in a Time of Debt*
- Herndon, Ash et Pollin
- Wray: combining data across centuries, exchange rate regimes,
## Les IRM fonctionnelles
- 2010: [Bennett et al.: le saumon
mort](https://www.researchgate.net/publication/255651552_Neural_correlates_of_interspecies_perspective_taking_in_the_post-mortem_Atlantic_Salmon_an_argument_for_multiple_comparisons_correction)
☺
- 2016: [Eklund, Nichols, and
Knutsson](http://www.pnas.org/content/113/28/7900.abstract). [Un bug
dans les logiciels d'IRM pourrait invalider 15 années de recherche
sur le
cerveau](http://www.sciencealert.com/a-bug-in-fmri-software-could-invalidate-decades-of-brain-research-scientists-discover)
(*40 000 articles*)
- 2016: C'est [plus subtil que
ça](https://www.cogneurosociety.org/debunking-the-myth-that-fmri-studies-are-invalid/).
[D'après Nichols, un des auteurs de l'article
d'origine](http://blogs.warwick.ac.uk/nichols/entry/bibliometrics_of_cluster/),
c'est plutôt de l'ordre de *3 600 études qui seraient
potentiellement impactées*.
## Les fausses structures de protéines
[A "buggy
software"](https://people.ligo-wa.caltech.edu/~michael.landry/calibration/S5/getsignright.pdf).
## Autres domaines
- [Oncologie](http://www.nature.com/nrd/journal/v10/n9/full/nrd3439-c1.html?foxtrotcallback=true):
"*half of published studies, even in prestigious journals, can't be
reproduced in industrial
labs*"
- [Psychologie](http://theconversation.com/we-found-only-one-third-of-published-psychology-research-is-reliable-now-what-46596):
"*attempting to reproduce 100 previously published findings*, *only
one-third of published psychology research was found to be
reliable*"
# M2-S2: Pourquoi est-ce difficile?
## Les erreurs classiques
- [Enquoi les ordinateurs ont "cassé" la
science](http://theconversation.com/how-computers-broke-science-and-what-we-can-do-to-fix-it-49938)
- [Erreurs de programmation et de manipulation de données en
génomique](https://qz.com/768334/years-of-genomics-research-is-riddled-with-errors-thanks-to-a-bunch-of-botched-excel-spreadsheets/)
## Tout rendre publique ?
- Quelqu'un pourrait [tirer parti de mon dur
labeur](http://www.nature.com/news/the-top-100-papers-1.16224)
# M2-S3: Le document computationnel : principe
# M2-S5: Travailler avec les autres
## Préparation d'un document pour un journal ou pour une conférence
De quoi aurez-vous besoin pour produire un document **pdf**:
- En interne: *pandoc*, *knitr* ou *emacs/org-mode*.
- *LaTeX* devra aussi être installé
Voici quelques billets intéressants sur le sujet:
- <http://blog.juliusschulz.de/blog/ultimate-ipython-notebook>
- <https://github.com/kirbs-/hide_code> is a
must-have
- <http://svmiller.com/blog/2016/02/svm-r-markdown-manuscript/>
- <https://github.com/balouf/Kleinberg/blob/master/KleinbergsGridSimulator.ipynb>
# M2-S6: Analyse comparée des différents outils
## [Exemples de document Org-Mode](../ressources/orgmode_examples/README_fr.org)
module3/ressources/iso_date_format.md deleted 100644 → 0
View file @ 8986dad7
---
TITLE: The ISO date format
Date: Fri Mar 8 09:33:11 2019
---
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) specifies the digital representation of date and time. For dates, which are of interest to us here, there are two different ways of proceeding: we can give the year, the month, and the day of the month, or we can give the year, the week, and the day of the week. August 8, 2018 can therefore be written `2018-08-08` or `2018-W32-3`, as it is the third day (Wednesday) of week 32 of 2018.
The definition of the week number requires some thought, as January 1st rarely falls on a Monday. What week is the first week of the year? The answer given by ISO 8601 is: the one that has more than half of its days in the new year, which is equivalent to the one that contains the first Thursday of the year. Consequently, it is quite possible, even frequent, that the first day of the first week of year *N* is in year *N-1*. To designate a whole week, we simply do not provide the day.
The Sentinel Network uses this definition of the week number, but does not respect the precise representation provided by ISO 8601. Instead of writing the third week of 1995 as `1995-W03`, it uses `199503`.
module3/ressources/iso_date_format_fr.md deleted 100644 → 0
View file @ 8986dad7
---
TITLE: Le format ISO pour les dates
Date: Fri Mar 8 09:33:11 2019
---
La norme [ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601) spécifie la représentation numérique de la date et de l'heure. Pour la date, qui nous intéresse ici, il y a deux façons différentes de procéder : on peut donner l'année, le mois, et le jour du mois, ou on peut donner l'année, la semaine, et le jour de la semaine. Le 8 août 2018 peut donc être écrit `2018-08-08` ou `2018-W32-3`, car il s'agit du troisième jour (mercredi) de la semaine 32 de l'année 2018.
La définition du numéro de la semaine nécessite un peu de réflexion, car le 1er janvier ne tombe que rarement sur un lundi. Quelle semaine est donc la première de l'année ? La réponse de la norme ISO 8601 est : celle qui a plus de la moitié de ses jours dans la nouvelle année, ce qui est équivalent à dire celle qui contient le premier jeudi de l'année. Par conséquent, il est tout à fait possible, même fréquent, que le 1er jour de la première semaine de l'année *N* tombe dans l'année *N-1*. Pour désigner une semaine entière, on ne fournit simplement pas le jour.
Le Réseau Sentinelles reprend cette définition du numéro de semaine, mais ne respecte pas la représentation précise prévue par la norme ISO 8601. Au lieu d'écrire la troisième semaine de 1995 comme `1995-W03`, il écrit `199503`.
module4/ressources/resources_environment.md deleted 100644 → 0
View file @ 8986dad7
---
title: Tracking environment information
date: Tue Feb 19 19:19:03 2019
---
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Getting information about your Git
repository](#getting-information-about-your-git-repository)
- [Getting information about Python(3)
libraries](#getting-information-about-python3-libraries)
- [Getting information about your
system](#getting-information-about-your-system)
- [Getting the list of installed packages and their
version](#getting-the-list-of-installed-packages-and-their-version)
- [How to list imported modules?](#how-to-list-imported-modules)
- [Saving and restoring an environment with
pip](#saving-and-restoring-an-environment-with-pip)
- [Installing a new package or a specific
version](#installing-a-new-package-or-a-specific-version)
- [Getting information about R
libraries](#getting-information-about-r-libraries)
- [Getting the list imported modules and their
version](#getting-the-list-imported-modules-and-their-version)
- [Getting the list of installed packages and their
version](#getting-the-list-of-installed-packages-and-their-version-1)
- [Installing a new package or a specific
version](#installing-a-new-package-or-a-specific-version-1)
# Getting information about your Git repository
When taking notes, it may be difficult to remember which version of the
code or of a file was used. This is what version control is useful for.
Here are a few useful commands that we typically insert at the top of
our notebooks in shell cells
``` shell
git log -1
```
``` example
commit 741b0088af5b40588493c23c46d6bab5d0adeb33
Author: Arnaud Legrand <arnaud.legrand@imag.fr>
Date: Tue Sep 4 12:45:43 2018 +0200
Fix a few typos and provide information on jupyter-git plugins.
```
``` shell
git status -u
```
``` example
On branch master
Your branch is ahead of 'origin/master' by 4 commits.
(use "git push" to publish your local commits)
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: resources.org
Untracked files:
(use "git add <file>..." to include in what will be committed)
../../module2/ressources/replicable_article/IEEEtran.bst
../../module2/ressources/replicable_article/IEEEtran.cls
../../module2/ressources/replicable_article/article.bbl
../../module2/ressources/replicable_article/article.tex
../../module2/ressources/replicable_article/data.csv
../../module2/ressources/replicable_article/figure.pdf
../../module2/ressources/replicable_article/logo.png
.#resources.org
no changes added to commit (use "git add" and/or "git commit -a")
```
*Note: the -u indicates that git should also display the contents of new
directories it did not previously know about.*
Then, we often include commands at the end of our notebook indicating
how to commit the results (adding the new files, committing with a clear
message and pushing). E.g.,
``` shell
git add resources.org;
git commit -m "Completing the section on getting Git information"
git push
```
``` example
[master 514fe2c1 ] Completing the section on getting Git information
1 file changed, 61 insertions(+)
Counting objects: 25, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (20/20), done.
Writing objects: 100% (25/25), 7.31 KiB | 499.00 KiB/s, done.
Total 25 (delta 11), reused 0 (delta 0)
To gitlab.inria.fr:learninglab/mooc-rr/mooc-rr-ressources.git
6359f8c..1f8a567 master -> master
```
Obviously, in this case you need to save the notebook before running
this cell, hence the output of this final command (with the new git
hash) will not be stored in the cell. This is not really a problem and
is the price to pay for running git from within the notebook itself.
# Getting information about Python(3) libraries
## Getting information about your system
This topic is discussed on
[StackOverflow](https://stackoverflow.com/questions/3103178/how-to-get-the-system-info-with-python).
``` python
import platform
print(platform.uname())
```
``` example
uname_result(system='Linux', node='icarus', release='4.15.0-2-amd64', version='#1 SMP Debian 4.15.11-1 (2018-03-20)', machine='x86_64', processor='')
```
## Getting the list of installed packages and their version
This topic is discussed on
[StackOverflow](https://stackoverflow.com/questions/20180543/how-to-check-version-of-python-modules).
When using `pip` (the Python package installer) within a shell command,
it is easy to query the version of all installed packages (note that on
your system, you may have to use either `pip` or `pip3` depending on how
it is named and which versions of Python are available on your machine
Here is for example how I get this information on my machine:
``` shell
pip3 freeze
```
``` example
asn1crypto==0.24.0
attrs==17.4.0
bcrypt==3.1.4
beautifulsoup4==4.6.0
bleach==2.1.3
...
pandas==0.22.0
pandocfilters==1.4.2
paramiko==2.4.0
patsy==0.5.0
pexpect==4.2.1
...
traitlets==4.3.2
tzlocal==1.5.1
urllib3==1.22
wcwidth==0.1.7
webencodings==0.5
```
In a Jupyter notebook, this can easily be done by using the `%%sh`
magic. Here is for example what you could do and get on the Jupyter
notebooks we deployed for the MOOC (note that here, you should simply
use the `pip` command):
``` python
%%sh
pip freeze
```
``` example
alembic==0.9.9
asn1crypto==0.24.0
attrs==18.1.0
Automat==0.0.0
...
numpy==1.13.3
olefile==0.45.1
packaging==17.1
pamela==0.3.0
pandas==0.22.0
...
webencodings==0.5
widgetsnbextension==3.2.1
xlrd==1.1.0
zope.interface==4.5.0
```
In the rest of this document, I will assume the correct command is `pip`
and I will not systematically insert the `%%sh` magic.
Once you know which packages are installed, you can easily get
additional information about a given package and in particular check
whether it was installed "locally" through pip or whether it is
installed system-wide. Again, in a shell command:
``` shell
pip show pandas
echo " "
pip show statsmodels
```
``` example
Name: pandas
Version: 0.22.0
Summary: Powerful data structures for data analysis, time series,and statistics
Home-page: http://pandas.pydata.org
Author: None
Author-email: None
License: BSD
Location: /usr/lib/python3/dist-packages
Requires:
Name: statsmodels
Version: 0.9.0
Summary: Statistical computations and models for Python
Home-page: http://www.statsmodels.org/
Author: None
Author-email: None
License: BSD License
Location: /home/alegrand/.local/lib/python3.6/site-packages
Requires: patsy, pandas
```
## How to list imported modules?
Without resorting to pip (that will list all available packages), you
may want to know which modules are loaded in a Python session as well as
their version. Inspired by
[StackOverflow](https://stackoverflow.com/questions/4858100/how-to-list-imported-modules),
here is a simple function that lists loaded package (that have a
`__version__` attribute, which is unfortunately not completely
standard).
``` python
def print_imported_modules():
import sys
for name, val in sorted(sys.modules.items()):
if(hasattr(val, '__version__')):
print(val.__name__, val.__version__)
else:
print(val.__name__, "(unknown version)")
print("**** Package list in the beginning ****");
print_imported_modules()
print("**** Package list after loading pandas ****");
import pandas
print_imported_modules()
```
``` example
**** Package list in the beginning ****
**** Package list after loading pandas ****
_csv 1.0
_ctypes 1.1.0
decimal 1.70
argparse 1.1
csv 1.0
ctypes 1.1.0
cycler 0.10.0
dateutil 2.7.3
decimal 1.70
distutils 3.6.5rc1
ipaddress 1.0
json 2.0.9
logging 0.5.1.2
matplotlib 2.1.1
numpy 1.14.5
numpy.core 1.14.5
numpy.core.multiarray 3.1
numpy.core.umath b'0.4.0'
numpy.lib 1.14.5
numpy.linalg._umath_linalg b'0.1.5'
pandas 0.22.0
_libjson 1.33
platform 1.0.8
pyparsing 2.2.0
pytz 2018.5
re 2.2.1
six 1.11.0
urllib.request 3.6
zlib 1.0
```
## Saving and restoring an environment with pip
The easiest way to go is as
follows:
``` shell
pip3 freeze > requirements.txt # to obtain the list of packages with their version
pip3 install -r requirements.txt # to install the previous list of packages, possibly on an other machine
```
If you want to have several installed Python environments, you may want
to use [Pipenv](https://docs.pipenv.org/). I doubt it allows to track
correctly FORTRAN or C dynamic libraries that are wrapped by Python
though.
## Installing a new package or a specific version
The Jupyter environment we deployed on our servers for the MOOC is based
on the version 4.5.4 of Miniconda and Python 3.6. In this environment
you should simply use the `pip` command (remember on your machine, you
may have to use `pip3`).
If I query the current version of `statsmodels` in a shell command, here
is what I will get.
``` shell
pip show statsmodels
```
``` example
Name: statsmodels
Version: 0.8.0
Summary: Statistical computations and models for Python
Home-page: http://www.statsmodels.org/
Author: Skipper Seabold, Josef Perktold
Author-email: pystatsmodels@googlegroups.com
License: BSD License
Location: /opt/conda/lib/python3.6/site-packages
Requires: scipy, patsy, pandas
```
I can then easily upgrade `statsmodels`:
``` shell
pip install --upgrade statsmodels
```
Then the new version should then be:
``` shell
pip show statsmodels
```
``` example
Name: statsmodels
Version: 0.9.0
Summary: Statistical computations and models for Python
Home-page: http://www.statsmodels.org/
Author: Skipper Seabold, Josef Perktold
Author-email: pystatsmodels@googlegroups.com
License: BSD License
Location: /opt/conda/lib/python3.6/site-packages
Requires: scipy, patsy, pandas
```
It is even possible to install a specific (possibly much older) version,
e.g.,:
``` shell
pip install statsmodels==0.6.1
```
# Getting information about R libraries
## Getting the list imported modules and their version
The best way seems to be to rely on the `devtools` package (if this
package is not installed, you should install it first by running in `R`
the command `install.packages("devtools")`).
``` r
sessionInfo()
devtools::session_info()
```
``` example
R version 3.5.1 (2018-07-02)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Debian GNU/Linux buster/sid
Matrix products: default
BLAS: /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.8.0
LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.8.0
locale:
[1] LC_CTYPE=fr_FR.UTF-8 LC_NUMERIC=C
[3] LC_TIME=fr_FR.UTF-8 LC_COLLATE=fr_FR.UTF-8
[5] LC_MONETARY=fr_FR.UTF-8 LC_MESSAGES=fr_FR.UTF-8
[7] LC_PAPER=fr_FR.UTF-8 LC_NAME=C
[9] LC_ADDRESS=C LC_TELEPHONE=C
[11] LC_MEASUREMENT=fr_FR.UTF-8 LC_IDENTIFICATION=C
attached base packages:
[1] stats graphics grDevices utils datasets methods base
loaded via a namespace (and not attached):
[1] compiler_3.5.1
Session info ------------------------------------------------------------------
setting value
version R version 3.5.1 (2018-07-02)
system x86_64, linux-gnu
ui X11
language (EN)
collate fr_FR.UTF-8
tz Europe/Paris
date 2018-08-01
Packages ----------------------------------------------------------------------
package * version date source
base * 3.5.1 2018-07-02 local
compiler 3.5.1 2018-07-02 local
datasets * 3.5.1 2018-07-02 local
devtools 1.13.6 2018-06-27 CRAN (R 3.5.1)
digest 0.6.15 2018-01-28 CRAN (R 3.5.0)
graphics * 3.5.1 2018-07-02 local
grDevices * 3.5.1 2018-07-02 local
memoise 1.1.0 2017-04-21 CRAN (R 3.5.1)
methods * 3.5.1 2018-07-02 local
stats * 3.5.1 2018-07-02 local
utils * 3.5.1 2018-07-02 local
withr 2.1.2 2018-03-15 CRAN (R 3.5.0)
```
Some actually advocate that [writing a reproducible research compendium
is best done by writing an R
package](https://github.com/ropensci/rrrpkg). Those of you willing to
have a clean R dependency management should thus have a look at
[Packrat](https://rstudio.github.io/packrat/).
## Getting the list of installed packages and their version
Finally, it is good to know that there is a built-in R command
(`installed.packages`) allowing to retrieve and list the details of all
packages installed.
``` r
head(installed.packages())
```
| Package | LibPath | Version | Priority | Depends | Imports | LinkingTo | Suggests | Enhances | License | License<sub>isFOSS</sub> | License<sub>restrictsuse</sub> | OS<sub>type</sub> | MD5sum | NeedsCompilation | Built | |
| ------------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- | ----------- | ---------------------------------------------------------- | -------------------------------------------------------------- | --------- | ------------- | ------------------------------------- | ------------------------------------ | ------------------------ | ------------------------------ | ----------------- | ------ | ---------------- | ----- | ----- |
| BH | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 1.66.0-1 | nil | nil | nil | nil | nil | nil | BSL-1.0 | nil | nil | nil | nil | no | 3.5.1 | |
| Formula | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 1.2-3 | nil | R (\>= 2.0.0), stats | nil | nil | nil | nil | GPL-2 | GPL-3 | nil | nil | nil | nil | no | 3.5.1 |
| Hmisc | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 4.1-1 | nil | lattice, survival (\>= 2.40-1), Formula, ggplot2 (\>= 2.2) | methods, latticeExtra, cluster, rpart, nnet, acepack, foreign, | | | | | | | | | | | |
| gtable, grid, gridExtra, data.table, htmlTable (\>= 1.11.0), | | | | | | | | | | | | | | | | |
| viridis, htmltools, base64enc | nil | chron, rms, mice, tables, knitr, ff, ffbase, plotly (\>= | | | | | | | | | | | | | | |
| 4.5.6) | nil | GPL (\>= 2) | nil | nil | nil | nil | yes | 3.5.1 | | | | | | | | |
| Matrix | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 1.2-14 | recommended | R (\>= 3.2.0) | methods, graphics, grid, stats, utils, lattice | nil | expm, MASS | MatrixModels, graph, SparseM, sfsmisc | GPL (\>= 2) | file LICENCE | nil | nil | nil | nil | yes | 3.5.1 |
| StanHeaders | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 2.17.2 | nil | nil | nil | nil | RcppEigen, BH | nil | BSD<sub>3clause</sub> + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | |
| acepack | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 1.4.1 | nil | nil | nil | nil | testthat | nil | MIT + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | |
## Installing a new package or a specific version
This section is mostly a cut and paste from the [recent post by Ian
Pylvainen](https://support.rstudio.com/hc/en-us/articles/219949047-Installing-older-versions-of-packages)
on this topic. It comprises a very clear explanation of how to proceed.
### Installing a pre-compiled version
If you're on a Debian or a Ubuntu system, it may be difficult to access
a specific version without breaking your system. So unless you are
moving to the latest version available in your Linux distribution, **we
strongly recommend you to build from source**. In this case, you'll need
to make sure you have the necessary toolchain to build packages from
source (e.g., gcc, FORTRAN, etc.). On Windows, this may require you to
install [Rtools](https://cran.r-project.org/bin/windows/Rtools/).
If you're on Windows or OS X and looking for a package for an **older
version of R** (R 2.1 or below), you can check the [CRAN binary
archive](https://cran-archive.r-project.org/bin/). Once you have the
URL, you can install it using a command similar to the example
below:
``` r
packageurl <- "https://cran-archive.r-project.org/bin/windows/contrib/2.13/BBmisc_1.0-58.zip"
install.packages(packageurl, repos=NULL, type="binary")
```
### Using devtools
The simplest method to install the version you need is to use the
`install_version()` function of the `devtools` package (obviously, you
need to install `devtools` first, which can be done by running in `R`
the command `install.packages("devtools")`). For instance:
``` r
require(devtools)
install_version("ggplot2", version = "0.9.1", repos = "http://cran.us.r-project.org")
```
### Installing from source code
Alternatively, you may want to install an older package from source If
devtools fails or if you do not want to depend on it, you can install it
from source via `install.packages()` directed using the right URL. This
URL can be obtained by browsing the [CRAN Package
Archive](https://cran.r-project.org/src/contrib/Archive).
Once you have the URL, you can install it using a command similar to the
example
below:
``` r
packageurl <- "http://cran.r-project.org/src/contrib/Archive/ggplot2/ggplot2_0.9.1.tar.gz"
install.packages(packageurl, repos=NULL, type="source")
```
If you know the URL, you can also install from source via the command
line outside of R. For instance (in
bash):
``` shell
wget http://cran.r-project.org/src/contrib/Archive/ggplot2/ggplot2_0.9.1.tar.gz
R CMD INSTALL ggplot2_0.9.1.tar.gz
```
### Potential issues
There are a few potential issues that may arise with installing older
versions of packages:
- You may be losing functionality or bug fixes that are only present
in the newer versions of the packages.
- The older package version needed may not be compatible with the
version of R you have installed. In this case, you will either need
to downgrade R to a compatible version or update your R code to work
with a newer version of the package.
module4/ressources/resources_environment_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Informations sur l'environnement
date: Tue Feb 19 19:19:03 2019
---
# Table des matières <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Obtenir des informations sur votre dépôt
Git](#obtenir-des-informations-sur-votre-dépôt-git)
- [Obtenir des informations sur les librairies Python
3](#obtenir-des-informations-sur-les-librairies-python-3)
- [Obtenir des informations sur votre
système](#obtenir-des-informations-sur-votre-système)
- [Lister les packages installés et leur
version](#lister-les-packages-installés-et-leur-version)
- [Lister les packages importés (chargés dans une session Python)
et leur
version](#lister-les-packages-importés-chargés-dans-une-session-python-et-leur-version)
- [Sauvegarder et restaurer un environnement avec
pip](#sauvegarder-et-restaurer-un-environnement-avec-pip)
- [Installer un nouveau package ou une version
spécifique](#installer-un-nouveau-package-ou-une-version-spécifique)
- [Obtenir des informations sur les packages
R](#obtenir-des-informations-sur-les-packages-r)
- [Lister les packages installés et leur
version](#lister-les-packages-installés-et-leur-version-1)
- [Lister les packages importés (chargés dans une session R) et
leur
version](#lister-les-packages-importés-chargés-dans-une-session-r-et-leur-version)
- [Installer un nouveau package ou une version
spécifique](#installer-un-nouveau-package-ou-une-version-spécifique-1)
# Obtenir des informations sur votre dépôt Git
Lorsqu'on prend des notes, il peut être difficile de se rappeler quelle
version de code ou de fichier a été utilisée. C'est l'intérêt du
contrôle de versions. Voici quelques commandes utiles que nous insérons
généralement au début de nos notebooks dans des cellules shell :
``` shell
git log -1
```
``` example
commit 741b0088af5b40588493c23c46d6bab5d0adeb33
Author: Arnaud Legrand <arnaud.legrand@imag.fr>
Date: Tue Sep 4 12:45:43 2018 +0200
Fix a few typos and provide information on jupyter-git plugins.
```
``` shell
git status -u
```
``` example
On branch master
Your branch is ahead of 'origin/master' by 4 commits.
(use "git push" to publish your local commits)
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: resources.org
Untracked files:
(use "git add <file>..." to include in what will be committed)
../../module2/ressources/replicable_article/IEEEtran.bst
../../module2/ressources/replicable_article/IEEEtran.cls
../../module2/ressources/replicable_article/article.bbl
../../module2/ressources/replicable_article/article.tex
../../module2/ressources/replicable_article/data.csv
../../module2/ressources/replicable_article/figure.pdf
../../module2/ressources/replicable_article/logo.png
.#resources.org
no changes added to commit (use "git add" and/or "git commit -a")
```
*Note : L'option -u indique que Git doit aussi afficher le contenu des
répertoires nouvellement créés.*
Nous ajoutons aussi souvent des commandes à la fin des notebooks pour
indiquer comment commiter les résultats (ajout des nouveaux fichiers,
commit avec un message clair et commande push). Par exemple :
``` shell
git add resources.org;
git commit -m "Completing the section on getting Git information"
git push
```
``` example
[master 514fe2c1 ] Completing the section on getting Git information
1 file changed, 61 insertions(+)
Counting objects: 25, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (20/20), done.
Writing objects: 100% (25/25), 7.31 KiB | 499.00 KiB/s, done.
Total 25 (delta 11), reused 0 (delta 0)
To gitlab.inria.fr:learninglab/mooc-rr/mooc-rr-ressources.git
6359f8c..1f8a567 master -> master
```
Évidemment, dans ce cas il faut enregistrer le notebook avant d'exécuter
cette cellule, donc le résultat de cette dernière commande (avec le
nouveau Git hash) ne sera pas stocké dans la cellule. Ce n'est pas
vraiment un problème et c'est le prix à payer pour exécuter Git à partir
du notebook lui-même.
# Obtenir des informations sur les librairies Python 3
## Obtenir des informations sur votre système
Cette question est discutée sur
[StackOverflow](https://stackoverflow.com/questions/3103178/how-to-get-the-system-info-with-python).
``` python
import platform
print(platform.uname())
```
``` example
uname_result(system='Linux', node='icarus', release='4.15.0-2-amd64', version='#1 SMP Debian 4.15.11-1 (2018-03-20)', machine='x86_64', processor='')
```
## Lister les packages installés et leur version
Cette question est discutée sur
[StackOverflow](https://stackoverflow.com/questions/20180543/how-to-check-version-of-python-modules).
Il est facile d'obtenir la version de tous les packages installés en
exécutant `pip` (l'installateur de packages Python) dans une commande
shell (la commande peut être `pip` or `pip3` selon la configuration de
votre ordinateur).
Voici par exemple comment j'obtiens ces informations sur ma machine :
``` shell
pip3 freeze
```
``` example
asn1crypto==0.24.0
attrs==17.4.0
bcrypt==3.1.4
beautifulsoup4==4.6.0
bleach==2.1.3
...
pandas==0.22.0
pandocfilters==1.4.2
paramiko==2.4.0
patsy==0.5.0
pexpect==4.2.1
...
traitlets==4.3.2
tzlocal==1.5.1
urllib3==1.22
wcwidth==0.1.7
webencodings==0.5
```
Dans un notebook Jupyter, cela peut facilement être fait en utilisant la
commande magique `%%sh`. Voici par exemple ce que vous pouvez faire et
obtenir avec les notebooks Jupyter que nous avons déployés pour le MOOC
(notez qu’ici vous devez simplement utiliser la commande `pip`) :
``` python
%%sh
pip freeze
```
``` example
alembic==0.9.9
asn1crypto==0.24.0
attrs==18.1.0
Automat==0.0.0
...
numpy==1.13.3
olefile==0.45.1
packaging==17.1
pamela==0.3.0
pandas==0.22.0
...
webencodings==0.5
widgetsnbextension==3.2.1
xlrd==1.1.0
zope.interface==4.5.0
```
Dans la suite de ce document, je supposerai que la commande correcte est
`pip` et je ne vais pas systématiquement insérer la commande magique
`%%sh`.
Une fois que vous savez quels packages sont installés, vous pouvez
facilement obtenir des informations supplémentaires sur un package donné
et notamment vérifier s'il a été installé "localement" via pip ou s'il
est installé à l'échelle du système. À nouveau dans une commande shell :
``` shell
pip show pandas
echo " "
pip show statsmodels
```
``` example
Name: pandas
Version: 0.22.0
Summary: Powerful data structures for data analysis, time series,and statistics
Home-page: http://pandas.pydata.org
Author: None
Author-email: None
License: BSD
Location: /usr/lib/python3/dist-packages
Requires:
Name: statsmodels
Version: 0.9.0
Summary: Statistical computations and models for Python
Home-page: http://www.statsmodels.org/
Author: None
Author-email: None
License: BSD License
Location: /home/alegrand/.local/lib/python3.6/site-packages
Requires: patsy, pandas
```
## Lister les packages importés (chargés dans une session Python) et leur version
Vous pouvez vouloir savoir quels packages sont chargés dans une session
Python ainsi que leur version sans recourir à pip (qui listera tous les
packages disponibles). Inspiré par
[StackOverflow](https://stackoverflow.com/questions/4858100/how-to-list-imported-modules),
voici une fonction simple qui liste les packages chargés (ayant un
attribut `__version__`, qui n’est malheureusement pas tout à fait
standard).
``` python
def print_imported_modules():
import sys
for name, val in sorted(sys.modules.items()):
if(hasattr(val, '__version__')):
print(val.__name__, val.__version__)
else:
print(val.__name__, "(unknown version)")
print("**** Package list in the beginning ****");
print_imported_modules()
print("**** Package list after loading pandas ****");
import pandas
print_imported_modules()
```
``` example
**** Package list in the beginning ****
**** Package list after loading pandas ****
_csv 1.0
_ctypes 1.1.0
decimal 1.70
argparse 1.1
csv 1.0
ctypes 1.1.0
cycler 0.10.0
dateutil 2.7.3
decimal 1.70
distutils 3.6.5rc1
ipaddress 1.0
json 2.0.9
logging 0.5.1.2
matplotlib 2.1.1
numpy 1.14.5
numpy.core 1.14.5
numpy.core.multiarray 3.1
numpy.core.umath b'0.4.0'
numpy.lib 1.14.5
numpy.linalg._umath_linalg b'0.1.5'
pandas 0.22.0
_libjson 1.33
platform 1.0.8
pyparsing 2.2.0
pytz 2018.5
re 2.2.1
six 1.11.0
urllib.request 3.6
zlib 1.0
```
## Sauvegarder et restaurer un environnement avec pip
La façon la plus simple de faire est la
suivante :
``` shell
pip3 freeze > requirements.txt # to obtain the list of packages with their version
pip3 install -r requirements.txt # to install the previous list of packages, possibly on an other machine
```
Si vous voulez avoir plusieurs environnements Python sur votre
ordinateur, vous pouvez vouloir utiliser
[Pipenv](https://docs.pipenv.org/) (mais je doute que cela permette de
tracer correctement les bibliothèques dynamiques FORTRAN ou C
encapsulées dans Python).
## Installer un nouveau package ou une version spécifique
L’environnement Jupyter que nous avons déployé sur nos serveurs pour le
MOOC est basé sur Miniconda 4.5.4 et Python 3.6. Dans cet environnement,
vous devez simplement utiliser la commande `pip` (vous devrez peut-être
utiliser `pip3` sur votre ordinateur).
Voici ce que j'obtiens si j'interroge la version actuelle de
`statsmodels` dans une commande shell.
``` shell
pip show statsmodels
```
``` example
Name: statsmodels
Version: 0.8.0
Summary: Statistical computations and models for Python
Home-page: http://www.statsmodels.org/
Author: Skipper Seabold, Josef Perktold
Author-email: pystatsmodels@googlegroups.com
License: BSD License
Location: /opt/conda/lib/python3.6/site-packages
Requires: scipy, patsy, pandas
```
Je peux alors facilement mettre `statsmodels` à jour :
``` shell
pip install --upgrade statsmodels
```
La nouvelle version devrait alors être :
``` shell
pip show statsmodels
```
``` example
Name: statsmodels
Version: 0.9.0
Summary: Statistical computations and models for Python
Home-page: http://www.statsmodels.org/
Author: Skipper Seabold, Josef Perktold
Author-email: pystatsmodels@googlegroups.com
License: BSD License
Location: /opt/conda/lib/python3.6/site-packages
Requires: scipy, patsy, pandas
```
Il est même possible d’installer une version spécifique (peut-être
beaucoup plus ancienne), par exemple :
``` shell
pip install statsmodels==0.6.1
```
# Obtenir des informations sur les packages R
## Lister les packages installés et leur version
Il existe une commande R intégrée (`installed.packages`) permettant de
récupérer et de lister les détails de tous packages installés.
``` r
head(installed.packages())
```
| Package | LibPath | Version | Priority | Depends | Imports | LinkingTo | Suggests | Enhances | License | License<sub>isFOSS</sub> | License<sub>restrictsuse</sub> | OS<sub>type</sub> | MD5sum | NeedsCompilation | Built | |
| ------------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- | ----------- | ---------------------------------------------------------- | -------------------------------------------------------------- | --------- | ------------- | ------------------------------------- | ------------------------------------ | ------------------------ | ------------------------------ | ----------------- | ------ | ---------------- | ----- | ----- |
| BH | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 1.66.0-1 | nil | nil | nil | nil | nil | nil | BSL-1.0 | nil | nil | nil | nil | no | 3.5.1 | |
| Formula | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 1.2-3 | nil | R (\>= 2.0.0), stats | nil | nil | nil | nil | GPL-2 | GPL-3 | nil | nil | nil | nil | no | 3.5.1 |
| Hmisc | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 4.1-1 | nil | lattice, survival (\>= 2.40-1), Formula, ggplot2 (\>= 2.2) | methods, latticeExtra, cluster, rpart, nnet, acepack, foreign, | | | | | | | | | | | |
| gtable, grid, gridExtra, data.table, htmlTable (\>= 1.11.0), | | | | | | | | | | | | | | | | |
| viridis, htmltools, base64enc | nil | chron, rms, mice, tables, knitr, ff, ffbase, plotly (\>= | | | | | | | | | | | | | | |
| 4.5.6) | nil | GPL (\>= 2) | nil | nil | nil | nil | yes | 3.5.1 | | | | | | | | |
| Matrix | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 1.2-14 | recommended | R (\>= 3.2.0) | methods, graphics, grid, stats, utils, lattice | nil | expm, MASS | MatrixModels, graph, SparseM, sfsmisc | GPL (\>= 2) | file LICENCE | nil | nil | nil | nil | yes | 3.5.1 |
| StanHeaders | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 2.17.2 | nil | nil | nil | nil | RcppEigen, BH | nil | BSD<sub>3clause</sub> + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | |
| acepack | /home/alegrand/R/x86<sub>64</sub>-pc-linux-gnu-library/3.5 | 1.4.1 | nil | nil | nil | nil | testthat | nil | MIT + file LICENSE | nil | nil | nil | nil | yes | 3.5.1 | |
## Lister les packages importés (chargés dans une session R) et leur version
Le meilleur moyen semble être d'utiliser le package `devtools`. Si le
package n'est pas installé, vous devez d'abord l'installer en exécutant
la commande `install.packages("devtools",dep=TRUE)` dans `R`).
``` r
sessionInfo()
devtools::session_info()
```
``` example
R version 3.5.1 (2018-07-02)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Debian GNU/Linux buster/sid
Matrix products: default
BLAS: /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.8.0
LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.8.0
locale:
[1] LC_CTYPE=fr_FR.UTF-8 LC_NUMERIC=C
[3] LC_TIME=fr_FR.UTF-8 LC_COLLATE=fr_FR.UTF-8
[5] LC_MONETARY=fr_FR.UTF-8 LC_MESSAGES=fr_FR.UTF-8
[7] LC_PAPER=fr_FR.UTF-8 LC_NAME=C
[9] LC_ADDRESS=C LC_TELEPHONE=C
[11] LC_MEASUREMENT=fr_FR.UTF-8 LC_IDENTIFICATION=C
attached base packages:
[1] stats graphics grDevices utils datasets methods base
loaded via a namespace (and not attached):
[1] compiler_3.5.1
Session info ------------------------------------------------------------------
setting value
version R version 3.5.1 (2018-07-02)
system x86_64, linux-gnu
ui X11
language (EN)
collate fr_FR.UTF-8
tz Europe/Paris
date 2018-08-01
Packages ----------------------------------------------------------------------
package * version date source
base * 3.5.1 2018-07-02 local
compiler 3.5.1 2018-07-02 local
datasets * 3.5.1 2018-07-02 local
devtools 1.13.6 2018-06-27 CRAN (R 3.5.1)
digest 0.6.15 2018-01-28 CRAN (R 3.5.0)
graphics * 3.5.1 2018-07-02 local
grDevices * 3.5.1 2018-07-02 local
memoise 1.1.0 2017-04-21 CRAN (R 3.5.1)
methods * 3.5.1 2018-07-02 local
stats * 3.5.1 2018-07-02 local
utils * 3.5.1 2018-07-02 local
withr 2.1.2 2018-03-15 CRAN (R 3.5.0)
```
Certains suggèrent même [l'écriture d'un package R pour faciliter la
recherche reproductible](https://github.com/ropensci/rrrpkg).
Ceux d'entre vous qui souhaitent disposer d'une gestion des dépendances
"propre" en R peuvent aussi jeter un coup d'œil à
[Packrat](https://rstudio.github.io/packrat/).
## Installer un nouveau package ou une version spécifique
Cette section est principalement un copier-coller du [récent post de Ian
Pylvainen](https://support.rstudio.com/hc/en-us/articles/219949047-Installing-older-versions-of-packages)
sur ce sujet. Il comprend une explication très claire de la façon de
procéder.
### Installer une version pré-compilée
Si vous êtes sur un système Debian ou Ubuntu, il peut être difficile
d’accéder à une version spécifique sans casser votre système. Donc,
sauf si vous passez à la dernière version disponible pour votre
distribution Linux, **nous vous recommandons fortement d'installer les
packages à l'aide des fichiers source**. Dans ce cas, vous devez vous
assurer que vous disposez de l'ensemble des outils nécessaires pour
créer des packages à partir des sources (par exemple : gcc, FORTRAN,
etc.). Sous Windows, il se peut que vous deviez installer
[Rtools](https://cran.r-project.org/bin/windows/Rtools/).
Si vous utilisez Windows ou OS X et recherchez un package pour une
**ancienne version de R** (version 2.1 ou inférieure), vous pouvez le
rechercher sur l'[archive binaire du site
CRAN](https://cran-archive.r-project.org/bin/). Une fois que vous avez
l'URL, vous pouvez l'installer à l'aide d'une commande similaire à
l'exemple
ci-dessous :
``` r
packageurl <- "https://cran-archive.r-project.org/bin/windows/contrib/2.13/BBmisc_1.0-58.zip"
install.packages(packageurl, repos=NULL, type="binary")
```
### Utiliser devtools
La méthode la plus simple pour installer la version dont vous avez
besoin consiste à utiliser la fonction `install_version()` du package
`devtools` (vous devez évidemment avoir préalablement installé
`devtools`, ce qui peut être fait en exécutant `R` la commande
`install.packages("devtools",dep=TRUE)`). Par exemple:
``` r
require(devtools)
install_version("ggplot2", version = "0.9.1", repos = "http://cran.us.r-project.org")
```
### Installer à partir du code source
Vous pouvez également installer un ancien package à partir de son code
source. Si vous ne réussissez pas avec devtools ou si vous ne voulez pas
dépendre de ce package, vous pouvez l’installer à partir du source à
l'aide de la commande `install.packages()` en utilisant la bonne URL.
Cette URL peut être obtenue en naviguant dans [l'archive de packages du
site CRAN](https://cran.r-project.org/src/contrib/Archive).
Une fois que vous avez l'URL, vous pouvez l'installer à l'aide d'une
commande similaire à l'exemple
ci-dessous :
``` r
packageurl <- "http://cran.r-project.org/src/contrib/Archive/ggplot2/ggplot2_0.9.1.tar.gz"
install.packages(packageurl, repos=NULL, type="source")
```
Si vous connaissez l'URL, vous pouvez également installer à partir du
source par ligne de commande en dehors de R. Par exemple (en
bash) :
``` shell
wget http://cran.r-project.org/src/contrib/Archive/ggplot2/ggplot2_0.9.1.tar.gz
R CMD INSTALL ggplot2_0.9.1.tar.gz
```
### Problèmes potentiels
Quelques problèmes sont susceptibles de survenir lors de l'installation
d'anciennes versions de packages :
- Vous pouvez perdre des fonctionnalités ou des corrections de bugs
qui ne sont présentes que dans les versions les plus récentes des
packages.
- L'ancienne version de package requise peut ne pas être compatible
avec la version de R que vous avez installée. Dans ce cas, vous
devrez soit rétrograder R vers une version compatible, soit mettre à
jour votre code R pour qu'il fonctionne avec une version plus
récente du package.
module4/ressources/resources_refs.md deleted 100644 → 0
View file @ 8986dad7
---
title: Additional references
date: Tue Feb 19 19:19:03 2019
---
# Table of Contents <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- ["Thoughts" on language/software
stability](#thoughts-on-languagesoftware-stability)
- [Controlling your software
environment](#controlling-your-software-environment)
- [Preservation/Archiving](#preservationarchiving)
- [Workflows](#workflows)
- [Numerical and statistical
issues](#numerical-and-statistical-issues)
- [Publication practices](#publication-practices)
- [Experimentation](#experimentation)
# "Thoughts" on language/software stability
As we explained, the programming language used in an analysis has a
clear influence on the reproducibility of your analysis. It is not a
characteristic of the language itself but rather a consequence of the
development philosophy of the underlying community. For example C is a
very stable language with a [very clear specification designed by a
committee](https://en.wikipedia.org/wiki/C_\(programming_language\)#ANSI_C_and_ISO_C)
(even though some compilers may not respect this norm).
On the other end of the spectrum,
[Python](https://en.wikipedia.org/wiki/Python_\(programming_language\))
had a much more organic development based on a readability philosophy
and valuing continuous improvement over backwards-compatibility.
Furthermore, Python is commonly used as a wrapping language (e.g., to
easily use C or FORTRAN libraries) and has its own packaging system. All
these design choices tend to make reproducibility often a bit painful
with Python, even though the community is slowly taking this into
account. The transition from Python 2 to the not fully backwards
compatible Python 3 has been a particularly painful process, not least
because the two languages are so similar that is it not always easy to
figure out if a given script or module is written in Python 2 or Python
3. It isn't even rare to see Python scripts that work under both Python
2 and Python 3, but produce different results due to the change in the
behavior of integer division.
[R](https://en.wikipedia.org/wiki/R_\(programming_language\)), in
comparison is much closer (in terms of developer community) to languages
like [SAS](https://en.wikipedia.org/wiki/SAS_\(software\)), which is
heavily used in the pharmaceutical industry where statistical procedures
need to be standardized and rock solid/stable. R is obviously not immune
to evolutions that break old versions and hinder
reproducibility/backward compatibility. Here is a relatively recent
[true story about
this](http://members.cbio.mines-paristech.fr/~thocking/HOCKING-reproducible-research-with-R.html)
and some colleagues who worked on the [statistics introductory course
with R on
FUN](https://www.fun-mooc.fr/courses/UPSUD/42001S06/session06/about)
reported us several issues with a few functions (`plotmeans` from
`gplots`, `survfit` from `survival`, or `hclust`) whose default
parameters had changed over the years. It is thus probably good practice
to give explicit values for all parameters (which can be cumbersome)
instead of relying on default values, and to restrict your dependencies
as much as possible.
This being said, the R development community is generally quite careful
about stability. We (the authors of this MOOC) believe that open source
(which allows to inspect how computation is done and to identify both
mistakes and sources of non-reproducibility) is more important than the
rock solid stability of SAS, which is proprietary software.
Yet, if you really need to stay with SAS, you should know that SAS can
be used within Jupyter using the [Python
SASPy](https://sassoftware.github.io/saspy/) and the [Python
SASKernel](https://sassoftware.github.io/sas_kernel/) packages (step by
step explanations about this are given
[here](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)).
Using such literate programming approach allied with systematic version
and environment control will always help. Similar solutions exist for
many languages ([list of Jupyter
kernels](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels)).
# Controlling your software environment
As we mentioned in the video sequences, there are several solutions to
control your environment:
- The easy (preserve the mess) ones:
[CDE](http://www.pgbovine.net/cde.html) or
[ReproZip](https://vida-nyu.github.io/reprozip/)
- The more demanding (encourage cleanliness) where you start with a
clean environment and install only what's strictly necessary (and
document it):
- The very well known [Docker](https://www.docker.io/)
- [Singularity](https://singularity.lbl.gov/) or
[Spack](https://spack.io/), which are more targeted toward the
specific needs of high performance computing users
- [Guix](https://www.gnu.org/software/guix/),
[Nix](https://nixos.org/) that are very clean (perfect?)
solutions to this dependency hell and which we recommend
It may be hard to understand the difference between these different
approaches and decide which one is better in your context.
Here is a webinar where some of these tools are demoed in a reproducible
research context: [Controling your environment (by Michael Mercier and
Cristian
Ruiz)](https://github.com/alegrand/RR_webinars/blob/master/2_controling_your_environment/index.org)
You may also want to have a look at [the Popper
conventions](http://falsifiable.us/) ([webinar by Ivo Gimenez through
google
hangout](https://github.com/alegrand/RR_webinars/blob/master/11_popper/index.org))
or at the [presentation of Konrad Hinsen on Active
Papers](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org)
(<http://www.activepapers.org/>).
# Preservation/Archiving
Ensuring software is properly archived, i.e, is safely stored so that it
can be accessed in a perennial way, can be quite tricky. If you have
never seen [Roberto Di Cosmo presenting the Software Heritage
project](https://github.com/alegrand/RR_webinars/blob/master/5_archiving_software_and_data/index.org),
this is a must see. <https://www.softwareheritage.org/>
For regular data, we highly recommend using <https://www.zenodo.org/>
whenever the data is not sensitive.
# Workflows
In the video sequences, we mentioned workflow managers (original
application domain in parenthesis):
- [Galaxy](https://galaxyproject.org/) (genomics),
[Kepler](https://kepler-project.org/) (ecology),
[Taverna](https://taverna.apache.org/) (bio-informatics),
[Pegasus](https://pegasus.isi.edu/) (astronomy), [Collective
Knowledge](http://cknowledge.org/) (compiling optimization),
[VisTrails](https://www.vistrails.org) (image processing)
- Light-weight: [dask](http://dask.pydata.org/) (python),
[drake](https://ropensci.github.io/drake/) (R),
[swift](http://swift-lang.org/) (molecular biology),
[snakemake](https://snakemake.readthedocs.io/) (like `make` but more
expressive and in `python`)…
- Hybrids: [SOS-notebook](https://vatlab.github.io/sos-docs/)…
You may want to have a look at this webinar:
\[\[<https://github.com/alegrand/RR_webinars/blob/master/6_reproducibility_bioinformatics/index.org>\]\[Reproducible
Science in Bio-informatics: Current Status, Solutions and Research
Opportunities (by Sarah Cohen Boulakia, Yvan Le Bras and Jérôme
Chopard).\]\]
# Numerical and statistical issues
We have mentioned these topics in our MOOC but we could by no way cover
them properly. We only suggest here a few interesting talks about
this.
- \[\[<https://github.com/alegrand/RR_webinars/blob/master/10_statistics_and_replication_in_HCI/index.org>\]\[In
this talk, Pierre Dragicevic provides a nice illustration of the
consequences of statistical uncertainty and of how some concepts
(e.G. p-values) are commonly badly
understood.\]\]
- \[\[<https://github.com/alegrand/RR_webinars/blob/master/3_numerical_reproducibility/index.org>\]\[Nathalie
Revol, Philippe Langlois and Stef Graillat present the main
challenges encountered when trying to achieve numerical
reproducibility and present recent research work on this topic.\]\]
# Publication practices
You may want to have a look at the following two webinars:
- [Enabling open and reproducible research at computer systems’
conferences (by Grigori
Fursin)](https://github.com/alegrand/RR_webinars/blob/master/8_artifact_evaluation/index.org).
In particular, this talk discusses *artifact evaluation* that is
becoming more and more popular.
- [Publication Modes Favoring Reproducible Research (by Konrad Hinsen
and Nicolas
Rougier)](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org).
In this talk, the motivation for the [ReScience
journal](http://rescience.github.io/) initiative are presented.
- [Simine Vazire - When Should We be Skeptical of Scientific
Claims?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), which is
discussing publication practices in social sciences and in
particular HARKing (Hypothesizing After the Results are Known),
p-hacking, etc.
# Experimentation
Experimentation was not covered in this MOOC, although it is an
essential part of science. The main reason is that practices and
constraints can vary so wildly from one domain to another that it could
not be properly covered in a first edition. We would be happy to gather
references you consider as interesting in your domain so do not hesitate
to provide us with such references by using the forum and we will update
this page.
- [A recent talk by Lucas Nussbaum on Experimental Testbeds in
Computer
Science](https://github.com/alegrand/RR_webinars/blob/master/9_experimental_testbeds/index.org).
module4/ressources/resources_refs_fr.md deleted 100644 → 0
View file @ 8986dad7
---
title: Références complémentaires
date: Tue Feb 19 19:19:03 2019
---
# Table des matières <span class="tag" data-tag-name="TOC"><span class="smallcaps">TOC</span></span>
- [Réflexions sur la stabilité des langages de
programmation](#réflexions-sur-la-stabilité-des-langages-de-programmation)
- [Contrôler votre environnement
logiciel](#contrôler-votre-environnement-logiciel)
- [Préservation/Archivage](#préservationarchivage)
- [Workflows](#workflows)
- [Problèmes numériques et
statistiques](#problèmes-numériques-et-statistiques)
- [Pratiques de publication](#pratiques-de-publication)
- [Expérimentation](#expérimentation)
# Réflexions sur la stabilité des langages de programmation
Comme nous l'avons expliqué, le langage de programmation utilisé dans
une analyse a une influence évidente sur la reproductibilité de
l'analyse. Ce n'est pas une caractéristique du langage lui-même mais
plutôt une conséquence de la philosophie de développement de la
communauté sous-jacente. Par exemple, C est un langage très stable avec
une [spécification très claire conçue par un
comité](https://en.wikipedia.org/wiki/C_\(programming_language\)#ANSI_C_and_ISO_C)
(même si certains compilateurs ne respectent cette norme).
À l’autre bout du spectre,
[Python](https://en.wikipedia.org/wiki/Python_\(programming_language\))
a connu un développement beaucoup plus organique basé sur une
philosophie de lisibilité et valorisant l'amélioration continue par
rapport à la compatibilité ascendante. De plus, Python est couramment
utilisé comme langage de wrapping (par exemple pour utiliser facilement
les bibliothèques C ou FORTRAN) et dispose de son propre système de
packaging. Tous ces choix de conception ont souvent tendance à rendre la
reproductibilité un peu pénible avec Python, même si la communauté en
tient lentement compte. La transition de Python 2 à Python 3, qui n'est
pas totalement compatible avec les versions antérieures, a été un
processus particulièrement pénible, notamment parce que les deux
langages sont si similaires qu'il n'est pas toujours facile de savoir si
un script ou un module donné est écrit en Python 2 ou Python 3. Il n'est
même pas rare de voir des scripts Python qui fonctionnent sous Python 2
et Python 3, mais produisent des résultats différents en raison du
changement de comportement de la division entière.
[R](https://en.wikipedia.org/wiki/R_\(programming_language\)), en
comparaison, est beaucoup plus proche (en termes de communauté de
développeurs) de langages comme
[SAS](https://en.wikipedia.org/wiki/SAS_\(logiciel\)), très utilisé dans
l'industrie pharmaceutique où les procédures statistiques doivent être
standardisées et stables/solides. R n’est évidemment pas à l’abri des
évolutions qui cassent les anciennes versions et gênent la
reproductibilité/compatibilité avec les versions antérieures. Voici une
[véritable histoire relativement récente à ce
sujet](http://members.cbio.mines-paristech.fr//thocking/HOCKING-reproducible-research-with-R.html)
et des collègues qui ont travaillé sur le [MOOC d'initiation à la
statistique avec R sur
FUN](https://www.fun-mooc.fr/courses/course-v1:UPSUD+42001+session10/about)
nous ont signalé plusieurs problèmes concernant quelques fonctions
(`gplots::plotmeans`, `survival::survfit` ou `hclust`) dont les
paramètres par défaut ont changé au fil des ans. Il est donc
probablement utile de donner des valeurs explicites pour tous les
paramètres (ce qui peut être fastidieux) au lieu de s’appuyer sur des
valeurs par défaut et de restreindre autant que possible vos
dépendances.
Ceci étant dit, la communauté de développement R est généralement très
prudente en matière de stabilité. Nous (les auteurs de ce MOOC) pensons
que l'open source (qui permet de contrôler le calcul et d'identifier les
erreurs et les sources de non-reproductibilité) est plus important que
la stabilité à toute épreuve de SAS, qui est un logiciel propriétaire.
Cependant, si vous avez vraiment besoin de rester sous SAS, sachez que
SAS peut être utilisé dans Jupyter en utilisant les packages Python
[SASPy](https://sassoftware.github.io/saspy/) et
[SASKernel](https://sassoftware.github.io/sas_kernel/) (tuto pas à pas
[ici](https://gitlab.inria.fr/learninglab/mooc-rr/mooc-rr-ressources/blob/master/documents/tuto_jupyter_windows/tuto_jupyter_windows.md#53-le-package-python-saspy-permet-dex%C3%A9cuter-du-code-sas-dans-un-notebook-python)).
L'utilisation d'une telle approche de programmation alphabète alliée à
un contrôle systématique de la version et de l'environnement est un
plus. Des solutions similaires existent pour de nombreux langages
([liste des kernels
Jupyter](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels)).
# Contrôler votre environnement logiciel
Comme nous l'avons mentionné dans les séquences vidéo, plusieurs
solutions permettent de contrôler votre environnement :
- Les faciles (autorisant le désordre) :
[CDE](http://www.pgbovine.net/cde.html) ou
[ReproZip](https://vida-nyu.github.io/reprozip/)
- Les plus exigeants (encourageant la propreté) où vous commencez avec
un environnement propre et n’installez que ce qui est strictement
nécessaire (et le documentez) :
- Le très connu [Docker](https://www.docker.io/)
- [Singularity](https://singularity.lbl.gov/) ou
[Spack](https://spack.io/), qui sont plus ciblés sur les besoins
spécifiques des utilisateurs d'informatique de haute performance
- [Guix](https://www.gnu.org/software/guix/),
[Nix](https://nixos.org/) qui sont des solutions très propres
(parfaites ?) à cet enfer de dépendance et que nous recommandons
Il peut être difficile de comprendre la différence entre ces différentes
approches et de décider laquelle est la meilleure dans votre contexte.
Voici un webinaire où certains de ces outils sont présentés dans un
contexte de recherche reproductible : [Controling your environment (by
Michael Mercier and Cristian
Ruiz)](https://github.com/alegrand/RR_webinars/blob/master/2_controling_your_environment/index.org).
Vous voudrez peut-être aussi jeter un coup d’œil sur la convention
[Popper](http://falsifiable.us/) ([webinaire par Ivo Gimenez par Google
hangout](https://github.com/alegrand/RR_webinars/blob/master/11_popper/index.org))
ou sur la [présentation de Konrad
Hinsen](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org)
sur [Active Papers](http://www.activepapers.org/).
# Préservation/Archivage
S'assurer que le logiciel est correctement archivé, c'est-à-dire qu'il
est stocké de manière sécurisée afin de pouvoir y accéder de manière
pérenne, peut être assez délicat. Si vous n'avez jamais vu la
[présentation du projet Software Heritage par Roberto Di
Cosmo](https://github.com/alegrand/RR_webinars/blob/master/5_archiving_software_and_data/index.org),
c'est à voir absolument. <https://www.softwareheritage.org/>
Pour les données, nous vous recommandons vivement d’utiliser
<https://www.zenodo.org/> lorsque les données ne sont pas sensibles.
# Workflows
Dans les séquences vidéo, nous avons mentionné les gestionnaires de flux
de travaux (domaine d'application d'origine entre parenthèses) :
- workflows assez complexes : [Galaxy](https://galaxyproject.org/)
(génomique), [Kepler](https://kepler-project.org/) (écologie),
[Taverna](https://taverna.apache.org/) (bioinformatique),
[Pegasus](https://pegasus.isi.edu/) (astronomie), [Collective
Knowledge](http://cknowledge.org/) (optimisation de la compilation),
[VisTrails](https://www.vistrails.org) (traitement d'image)
- workflows plus légers : [dask](http://dask.pydata.org/) (Python),
[drake](https://ropensci.github.io/drake/) (R),
[swift](http://swift-lang.org/) (biologie moléculaire),
[snakemake](https://snakemake.readthedocs.io/) (comme `make` mais
plus expressif et en `Python`)…
- hybride à mi-chemin entre le notebook et le workflow :
[SOS-notebook](https://vatlab.github.io/sos-docs/)
Vous voudrez peut-être consulter ce webinaire :
\[\[<https://github.com/alegrand/RR_webinars/blob/master/6_reproducibility_bioinformatics/index.org>\]\[Science
Reproducible en Bioinformatique : état actuel, solutions et opportunités
de recherche (par Sarah Cohen Boulakia, Yvan Le Bras and Jérôme
Chopard)\]\].
# Problèmes numériques et statistiques
Nous avons mentionné ces sujets dans notre MOOC mais nous ne pourrions
en aucun cas les couvrir correctement. Nous ne suggérons ici que
quelques présentations intéressantes à ce
sujet.
- \[\[<https://github.com/alegrand/RR_webinars/blob/master/10_statistics_and_replication_in_HCI/index.org>\]\[Pierre
Dragicevic donne une belle illustration des conséquences de
l’incertitude statistique et de la manière dont certains concepts
(par exemple les p-values) sont généralement mal
compris\]\].
- \[\[<https://github.com/alegrand/RR_webinars/blob/master/3_numerical_reproducibility/index.org>\]\[Nathalie
Revol, Philippe Langlois et Stef Graillat présentent les principaux
problèmes rencontrés en essayant d'obtenir une reproductibilité
numérique et présentent les travaux de recherche récents en la
matière\]\].
# Pratiques de publication
Vous souhaiterez peut-être consulter les webinaires suivants :
- [Permettre une recherche ouverte et reproductible lors de
conférences sur les systèmes informatiques (par Grigori
Fursin)](https://github.com/alegrand/RR_webinars/blob/master/8_artifact_evaluation/index.org).
En particulier, cette discussion aborde *l'évaluation des artefacts*
qui devient de plus en plus populaire.
- [Modalités de publication favorisant la recherche reproductible (par
Konrad Hinsen et Nicolas
Rougier)](https://github.com/alegrand/RR_webinars/blob/master/7_publications/index.org).
Présentation des motivations de l'intiative [ReScience
journal](http://rescience.github.io/).
- [Simine Vazire - Quand devrions-nous être sceptiques face aux
affirmations
scientifiques ?](https://www.youtube.com/watch?v=HuJ2G8rXHMs), qui
traite des pratiques de publication dans les sciences sociales et en
particulier HARKing (Hypothèses après que les résultats sont
connus), p-hacking, etc.
# Expérimentation
L'expérimentation n'est pas couverte dans ce MOOC bien qu'il s'agisse
d'un élément essentiel de la science. La raison principale est que les
pratiques et les contraintes varient tellement d'un domaine à l'autre
que ce thème ne pouvait pas être correctement couvert dans une première
édition. Nous serions heureux de rassembler les références que vous
jugez intéressantes dans votre domaine. N'hésitez donc pas à nous les
fournir à l'aide du forum. Nous les intégrerons dans cette page.
- [Une récente conférence de Lucas Nussbaum sur les bancs d’essais
expérimentaux en
informatique](https://github.com/alegrand/RR_webinars/blob/master/9_experimental_testbeds/index.org).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment