2 Rédaction d’un compte-rendu en utlisant le template cr-urca

2.1 Structure d’un document .Rmd

Le fichier .Rmd généré par l’utilisation du template cr-urca (et à vrai dire, tout fichier d’extension .Rmd) est constitué de trois composantes :

un bloc d’en-tête délimité par deux triplets de tirets (---) contenant les paramètres du document (appelées méta-données), tels que le nom de l’auteur, le diplôme, le nom du fichier de bibliograhie, etc. La syntaxe utilisée ici est celle du langage YAML⁴ assurant l’incorporation des méta-données dans certains fichiers intermédiaires ;
le corps du document, rédigé selon la syntaxe du langage Markdown ;
des blocs de code (“chunks” en anglais), délimités par des triplets d’accents graves. Le triplet d’accents ovrant le bloc est suivi d’instructions délimités par des accolades ouvrantes et fermantes contenant le nom du langage et certains paramètres décrivant les éléments devant figurer dans le fchier de sortie (le code doit-il être affiché ? le résultat de son exécution ? etc.).

2.2 L’en-tête YAML

L’en-tête YAML contient les éléments suivants, qui peuvent (doivent) être modifiés :

title : le titre du compte-rendu tel qu’il apparaîtra sur la page de garde du document généré. Ce titre appaîtra également en en-tête de chaque page ;
author : le ou les auteur(s) du compte-rendu. Si plusieurs auteurs, la liste doit être saisie comme indiqué dans le fichier d’exemple produit lors de la création d’un fichier R Markdown selon le template cr-urca ;
email : la ou les adresse(s) mail du ou des auteur(s) ;
date : la date de création du document ; par défaut, c’est la date du jour de la dernière compilation ;
abstract : un paragraphe résumant le contenu du compte-rendu ;
anac : l’année académique ;
diplome : le diplôme dans lequel est inscrit l’auteur du compte-rendu ;
module : l’intitulé du module d’enseignement dans le cadre duquel le compte-rendu est rédigé ;
enseig : l’enseignant référent pour ce module ;
evaluation : le type d’évaluation auquel répond ce compte-rendu. Par exmeple “Compte-rendu de travaux pratiques n°1 (CRTP1)” ou “Compte-rendu d’analyse statistique” ;
bibliography : pointe vers le fichier d’extension .bib contenant les références. Par défaut, ce fichier est nommé Biblio_cr-urca.bib et est créé en même temps que le fichier .Rmd

On peut utiliser des fonctions de R retournant un vecteur de chaînes de caractères, tels que paste ou Sys.Date, en insérant un morceau de code en ligne et en l’entourant de guillemets doubles. Lors de la compilation du document, ces instructions sont en premier lieu évaluées par R ; le résultat de leur exécution est incorporé (en tant que texte, donc sans les guillets délimitant la chaîne résultat) dans le fichier cible intermédiaire. Dans le cas présent, le fichier cible est un fichier d’extension .tex ; il est donc possible que la chaîne de caractère passée en argument soit une ligne de code LaTeX comme c’est le cas pour la valeur par défaut renseignée pour le diplôme dans le fichier .Rmd.

Sauf expertise de l’auteur sur le fonctionnement de R Markdown, il est recommandé de NE PAS modifier le reste de l’en-tête.

2.3 Syntaxe Markdown

Le corps du compte-rendu est à rédiger dans le langage Markdown. Son apprentissage est extrêmement rapide ; une heure devrait suffire pour se familiariser avec les balises les plus usuelles. En guise d’introduction, on pourra consulter la Section 2.5 de (Xie, Allaire, and Grolemund 2018). Ne pas hésiter également à copier et adapter des morceaux des fichiers fournis en exemple.

Rstudio incorpore un aide-mémoire des balises Markdown les plus usuelles ; on y accède depuis le menu : cliquer sur Help puis Markdown Quick Reference.

2.4 Insertion de code R

On peut incorporer des blocs de code R au document .Rmd de sorte que le code lui-même et/ou le résultat de son exécution soi(en)t incorporé au document généré. Encore une fois, on renvoie à la Section 2.6 de (Xie, Allaire, and Grolemund 2018) ainsi qu’aux fichiers fournis pour une prise en main de ces fonctionnalités.

Il est important d’avoir conscience que lors de la compilation du document .Rmd, une session propre de R, indépendante de celle apparaissant dans l’onglet Console de Rstudio, est utilisée. La conséquence pratique la plus notable est qu’aucune variable de l’environnement de la session R utilisée par l’auteur n’est accessible. Le premier bloc de code R à insérer correspond donc souvent à l’importation des données utilisées et au chargement des packages nécessaires.

2.5 Les fonctionnalités fournies par `bookdown`

Le template cr-urca utilise le package bookdown pour la compilation du document .Rmd. Ce package fournit quelques fonctionnalités intéressantes (indispensables ?) pour la conception de compte-rendus de qualité : prise en charge des références croisées vers les figures, tables, équations, théorèmes, parties et sous-parties du document, gestion de la bibliographie. On renvoie aux Sections 2.2 à 2.8 de l’ouvrage (Xie 2016) pour une présentation de ces fonctionnalités, ainsi qu’aux exemples présents dans les fichiers fournis en exemple ou d’autres fichiers d’extension .Rmd accessibles en ligne.

Les références sont à cataloguer dans un fichier (nommé par défaut biblio_cr-urca.bib) au format BibTeX, respectant la syntaxe de ce format. Un exemple d’entrée pour ce fichier est :

@Book{rmarkdown_refbook2018,
    title = {R Markdown: The Definitive Guide},
    author = {Yihui Xie and J.J. Allaire and Garrett Grolemund},
    publisher = {Chapman and Hall/CRC},
    address = {Boca Raton, Florida},
    year = {2018},
    note = {ISBN 9781138359338},
    url = {https://bookdown.org/yihui/rmarkdown},
  }

La première ligne précise le type de document (@Book) ainsi que le label de cette référence à utiliser dans le document .Rmd, ici rmarkdown_refbook2018. Pour faire référence à cet ouvrage dans le corps du document .Rmd, on tapera simplement [@rmarkdown_refbook2018] ; cette instruction sera remplacé par la référence adéquate lors de la compilation.

Pour constituer le fichier BibTeX sans trop se fatiguer, on peut procéder ainsi :

Si l’on est amené à citer des packages R ou des ouvrages de référence sur ces packages, la commande citation de R permet d’obtenir les entrées correspondantes. Voici un exemple pour le package bookdown.

print(citation('bookdown'), bibtex = TRUE)


To cite the 'bookdown' package in publications use:

  Yihui Xie (2020). bookdown: Authoring Books and Technical Documents
  with R Markdown. R package version 0.18.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {bookdown: Authoring Books and Technical Documents with R Markdown},
    author = {Yihui Xie},
    year = {2020},
    note = {R package version 0.18},
    url = {https://github.com/rstudio/bookdown},
  }

  Yihui Xie (2016). bookdown: Authoring Books and Technical Documents
  with R Markdown. Chapman and Hall/CRC. ISBN 978-1138700109

A BibTeX entry for LaTeX users is

  @Book{,
    title = {bookdown: Authoring Books and Technical Documents with {R} Markdown},
    author = {Yihui Xie},
    publisher = {Chapman and Hall/CRC},
    address = {Boca Raton, Florida},
    year = {2016},
    note = {ISBN 978-1138700109},
    url = {https://github.com/rstudio/bookdown},
  }

Pour faire référence à des articles scientifiques, on peut utiliser Google Scholar. On effectue une recherche via ce site pour trouver la référence souhaitée puis on clique sur l’icône en forme de guillemet et enfin sur le lien intitulé Bibtex.
On peut utiliser le logiciel de gestion de références bibliographiques Zotero.

Dans tous les cas, il suffit de copier le ou les blocs d’intérêt dans le fichier BibTeX et penser à ajouter, dans chaque bloc, le label pour cette référence.

Le langage YAML, acronyme autoréférent pour “YAML Ain’t Markup Langage”, est un langage et un format de représentation de données développé par Clarck Evans, dont la première version date de 2001.↩