8 Quarto

8.1 Introduction

Vous utilisez peut-être Microsoft Excel pour l’analyse de données et Microsoft Word pour la communication de vos résultats dans un document de texte. Bien que ces logiciels soient très utiles, ils ne sont pas suffisants pour les besoins des scientifiques. Normalement, on a besoin de trois éléments (c’est-à-dire trois types d’outils) dans le monde académique/scientifique :

l’analyse de données
la composition des documents (articles, diapos, affiches, livres)
la gestion des références bibliographiques

Le système Quarto

Il y a plusieurs options pour chaque élément ci-dessus. Dans les sciences sociales, beaucoup de gens utilisent SPSS pour l’analyse de données, Microsoft Word pour la composition des articles et des livres, et EndNote pour la gestion des références, par exemple. Mais cette combinaison d’outils n’est pas de tout la meilleure option disponible. On pourrait utiliser R pour l’analyse de données, \(\LaTeX\) pour la composition des documents et pour la gestion de références (bibtex). \(\LaTeX\) est un langage et un système de composition de documents. J’utilise ce système pour tous mes documents : les diapos utilisées en classe sont créées avec \(\LaTeX\). Le problème avec \(\LaTeX\) est la courbe d’apprentissage : c’est un système difficile à apprendre. Heureusement, on peut l’utiliser indirectement.

Dans notre cours, on va utiliser Quarto dans RStudio. Simplement dit, Quarto nous permet d’utiliser R et \(\LaTeX\) dans un même document. La partie de l’analyse de données aura des codes R, et la partie textuelle sera écrite avec Markdown, un langage très simple pour produire des documents. Imaginez un logiciel qui combine Microsoft Word et Excel dans le même document.

Il y a trois avantages d’utiliser Markdown :

C’est un langage très simple à apprendre
Le langage peut être traduise vers plusieurs types de document : PDF avec \(\LaTeX\), doc, HTML
La gestion de références bibliographiques peut être automatisée

Pour nos deux projets, on va utiliser Quarto à partir d’un modèle spécifique. Ici, on va examiner comment créer notre premier document avec Quarto.

Une alternative plus facile et rapide?

Depuis 2019, il existe une nouvelle option pour générer des documents PDF. Il s’agit d’un nouveau langage de balisage appelé Typst. Pour l’utiliser, il faut remplacer PDF par typst comme le format standard (consultez la figure ci-dessous et la dernière section de cette page).

8.2 Installation

Pour créer votre premier document Quarto, cliquez sur File > New File > Quarto Document.... Après, sélectionnez PDF et désélectionnez Use visual markdown editor.

Pour utiliser Quarto, il faudra installer quelques extensions. RStudio affichera une notification pour les installer. Suivez les instructions.

8.3 Un modèle

Chaque document Quarto (*.Qmd) commence avec le préambule : c’est ici que l’on spécifie le titre, le format, l’auteur, la date, etc. Heureusement, on pourrait créer un modèle complet et copier son préambule pour créer un nouveau document. Le préambule se trouve entre les deux séquences de trois traits d’union : ---. Voici un exemple.

---
title: "Mon document"
author: "Guilherme D. Garcia"
number-sections: true
date: today
lang: fr
format: pdf # typst serait une autre option pour les PDFs
bibliography: references.bib
---

# Introduction{#sec-intro}

Voici ma première section. Notez l'étiquette entre {}.

...

Dans notre cours, on travaille avec le format PDF, mais on va tester le format HTML aussi — cette page-ci a été créée avec Quarto (HTML). Après avoir défini notre préambule, on commence avec la première section : l’introduction. Vu que les documents Quarto utilisent le langage Markdown, les sections sont signalées par un #; les sous-sections seront signalées par ##, etc.

Markdown

Pour apprendre les commandes les plus importantes en Markdown, visitez la page de Quarto.

La séquence {#sec-intro} est une étiquette pour la section de l’introduction. Cela nous permet de créer une référence croisée en utilisant la commande @sec-intro. On examine ce type de possibilité dans la séance. Finalement, le préambule contient une ligne pour la bibliography. Il faut avoir un fichier *.bib qui contient notre bibliothèque de références. Un fichier .bib est simplement un fichier de texte. Voici un exemple :

@book{Barnier2023,
  title         = {Introduction à R et au tidyverse},
  author        = {Barnier, Julien},
  year          = {2023}
}

Dans l’exemple ci-dessus, Barnier2023 sera notre mot-clé (on décide quel nom on utilisera; c’est comme une variable en R). Après avoir défini cette entrée dans notre bibliothèque, on peut citer le livre en question en utilisant la commande @Barnier2023, ce qui sera compilé comme « Barnier (2023) » dans notre document. En plus, l’entrée sera ajoutée à la fin du document, dans la section « Références ». Naturellement, on n’a pas besoin de créer chaque référence manuellement. Au lieu de cela, on utilise des outils tels que Google Scholar pour copier et coller chaque référence dans notre fichier *.bib.

Finalement, pour produire un document quarto, on aura :

Un fichier Qmd
Un fichier bib pour nos références
Les figures (selon le besoin)

À partir de ces fichiers, Quarto générera notre document en PDF (ou en HTML). Le modèle utilisé dans la séance peut être téléchargé ici.

8.4 Un modèle `Typst`

Si vous préférez le format Typst, voici un exemple. Bien que le système soit nouveau et qu’il ne soit pas aussi puissant que \(\LaTeX\), il est certainement plus facile à installer, à apprendre et à utiliser; sa compilation est également plus rapide. Consultez la page Quarto Typst ici.

---
title: "Mon document"
author: "Guilherme D. Garcia"
number-sections: true
date: "2023-10-10"
format: typst
citeproc: true
bibliography: references.bib
crossref: 
  fig-title: "Figure"
  tbl-title: "Tableau"
  title-delim: "."
  fig-prefix: "Fig."
  tbl-prefix: "Tableau"
  sec-prefix: "Section"
---

# Introduction{#sec-intro}

Selon @Barnier2023, la relation entre...

## Questions

Dans la @sec-intro, on a vu que...

# Références

Pratique

Question 1. Créez un document PDF avec Quarto pour vos réponses aux questions 7–9 du chapitre 7. Chaque question aura une section, un petit paragraphe de texte, les codes que vous avez utilisés, et leurs résultats.

Question 2. Dans votre texte, vous devez citer deux œuvres : R et tidyverse. Donc, vous devrez créer un fichier bib ainsi qu’un fichier Qmd. Consultez la suggestion ci-dessous.

Question 3. Changez le format de votre document Quarto en doc et en HTML pour vérifier les différents types d’output possibles.

Comment trouver vos références?

Pour consulter la référence du langage R, exécutez citation(). Pour les extensions utilisées, exécutez citation("nom_de_l'extension") et voilà. Après, copiez le résultat et collez-le dans votre fichier bib. Pour toutes les autres références, Google Scholar est probablement l’option la plus simple. Cherchez l’œuvre d’intérêt, cliquez sur « citer » et après sur « BibTeX ». Plusieurs sites utilisent le format bib pour leurs citations. Donc, ce ne pas difficile de trouver la référence que vous cherchez. Finalement, il est toujours possible de l’ajouter manuellement (dernier recours).