Rédiger un article

1. Le modèle d’article Rzine

Le modèle d’article Rzine repose sur le système open-source Quarto, pour la publication d’articles scientifiques et techniques. Quarto peut être utilisé en ligne de commande ou via des IDE comme RStudio ou Visual studio code.

Le modèle de mise en page Rzine est disponible sur ce dépôt GitLab : https://gitlab.huma-num.fr/rzine/rzine-template Vous pouvez le télécharger directement en archive ZIP en cliquant sur ce lien.

Le modèle de mise en page regroupe les fichiers suivants :

un document Quarto index.qmd, qui contient le code source de l’article.
Un fichier BibTeX bibliography.bib, pour les références bibliographiques utilisées dans l’article.
Un dossier data, pour les données mobilisées dans l’article.
Un dossier figures, pour les éventuelles images incluses dans la publication.
Un fichier Projet Rstudio rzine_template.Rproj
Un fichier README.md, à compléter pour la soumission.
Un dossier _extensions, contient des éléments de mise en page. À ne pas modifier.

2. Compiler l’article

Etant tous les deux développés par l’entreprise Posit, le système Quarto est intégré par défaut dans l’IDE Rstudio. Il suffit donc d’avoir une version récente de Rstudio pour produire un article Rzine.

Un fois l’archive du modèle de mise en page décompressée, ouvrez le projet Rstudio rzine_template.Rproj. Une fois dans le projet, ouvrez le fichier index.qmd, fichier source de l’article.

Vous pouvez compiler le document en utilisant le bouton Render dans l’interface RStudio. La compilation du fichier index.qmd engendre l’exécution des blocs de code et la mise en page du document dans le format HTML. :

Il est également possible de compiler le fichier depuis le terminal en utilisant la commande quarto render:

quarto render document.qmd # all formats
quarto render document.qmd --to pdf

Une fois la compilation terminée, un fichier HTML du même nom est enregistré à la racine du répertoire projet. Il s’agit de l’article mis en page, prêt à la publication. Il ne vous reste plus qu’à rédiger l’article……

Documentation officielle : https://quarto.org/docs/get-started/hello/rstudio.html#rendering

3. Métadonnées principales

L’en-tête (YAML) d’un document Quarto (.qmd) est délimité par deux lignes de 3 tirets. Il contient les métadonnées de l’article et les paramètres de mise en forme du document.

---
title: Titre 
subtitle: Sous-titre 
date: today
authors:
  - name: Prénom Nom
    affiliations: Laboratoire, Organisme
    orcid: 0000-0000-0000-0000
  - name: Prénom Nom
    affiliations: Laboratoire, Organisme
    orcid: 0000-0000-0000-0000
doi: 10.00000/xxxx-xxxx
abstract: |
    Résumé court de la publication (50 mots maximum)
keywords: 
- mot-clé 
- mot-clé 2
- etc.

bibliography: bibliography.bib
lang: fr-FR
embed-resources: true
format:
  rzine-html: default
---

Sans modifier l’indentation, indiquez-y les informations suivantes :

Titre de l’article
Sous-titre de l’article
Nom(s) prénom(s) des auteur·es
Unité(s) et/ou organisme(s) de rattachement
Numéro(s) ORCID des auteur·es
Résumé court de la publication (50 mots maximum)
Une liste de mots clefs

Documentation officielle : https://quarto.org/docs/output-formats/html-basics.html

4. Corps du document

Comme tous les systèmes de notebook, un document Quarto permet d’entremêler du texte et des blocs de code.

4.1 Texte en markdown

Le contenu écrit de votre contribution, présentant votre démarche et explicitant la succession des traitements partagés est à mettre en forme en markdown. Ce langage de balisage léger est simple et rapide à maîtriser. De nombreuses ressources sont à votre disposition sur le web.

Guide de démarrage : https://quarto.org/docs/output-formats/html-basics.html
Markdown pour Quarto : https://quarto.org/docs/authoring/markdown-basics.html#overview

4.2 Bloc de code (chunks)

Le code R est à inclure dans des chunks. Pour insérer un nouveau chunks R, plusieurs solutions possibles :

a.Utiliser le menu Code > Insert Chunk de RStudio.
b. Utiliser le raccourci clavier Ctrl+Alt+i
c. Copier-coller les lignes suivantes :

```{r}
  
```

d. Cliquez sur le bouton suivant dans la barre d’outil Rstudio :

Tous un ensemble d’options peut être spécifié en début de chunk de la manière suivante :

```{r}
#| fig-cap: Un plot de base
#| eval: true
#| echo: fenced
#| include: true
#| fig-height: 3
#| fig-width: 7
#| label: fig-1

plot(1:10)
```

Documentation officielle : https://quarto.org/docs/computations/execution-options.html .

Bien qu’il s’agisse d’un notebook, nous vous invitons tout de même à ajouter des commentaires dans les blocs de code.

```{r}
#| fig-cap: Un plot de base commenté
#| eval: true
#| echo: fenced

# Graphique
plot(1:10)
```

4.3 Insérer une image

Les images insérées dans l’article sont à déposer dans le dossier figures. Il existe plusieurs façons d’insérer une image dans un document Quarto. Pour un référencement optimal de la figure (label, numérotation, citation), nous vous recommandons l’utilisons du langage R.

Créez un nouveau chunk et utilisez la fontion include_graphics() du package knitr :

```{r}
#| fig-cap: "Une bien belle image"
#| echo: fenced
#| fig-width: 7 
#| label: fig-1

knitr::include_graphics("figures/rzine-collection.png")
```

4.4 Équations

Il est possible d’écrire des formules mathématiques en langage $\TeX$. Pour cela, délimitez le contenu $\LaTeX$ par un ou deux symboles $ :

$$ y = \sqrt{\frac{1}{x + \beta}} $$

En mode Inline ($) , les formules sont incluses à l’intérieur du paragraphe courant. En mode Displayed ($$), elles apparaissent centrées et mises en exergue, exemple :

\[y = \sqrt{\frac{1}{x + \beta}}\]

Documentation officielle : https://quarto.org/docs/visual-editor/technical.html

4.5 Callouts blocks

Les callouts block peuvent être utilisés pour attirer l’attention sur certains points. Leur syntaxe est très simple d’utilisation :

:::{.callout-tip}
## Intéressés par la collection Rzine ?
    
Consultez les [articles](https://rzine.fr/articles_rzine/) déjà publiés !
:::

Documentation officielle : https://quarto.org/docs/authoring/callouts.html

5. Données

Tout·e lecteur·ice doit être en mesure de reproduire la démonstration de l’article sans contrainte de réutilisation. L’intégralité des données utilisées doivent obligatoirement être :

Correctement présentées dans l’article.
Libre d’utilisation et de diffusion.
Mises à disposition des lecteur·rice·s, même si ces données sont déjà en libre accès.
Décrites par des métadonnées.
Respectueuses du règlement général sur la protection des données.

Toutes les données utilisées dans l’article devront être stockées dans le répertoire data.

6. Bibliographie

Les références bibliographiques utilisées sont à saisir en format BibTeX dans le fichier bibliographie.bib. Exemple :

@book{CameronTrivedi2013,
  author    = {A. Colin Cameron and Pravin K. Trivedi},
  title     = {Regression Analysis of Count Data},
  year      = {2013},
  edition   = {2nd},
  publisher = {Cambridge University Press},
  address   = {Cambridge}
}

Pour appeler une référence en markdown dans le corps du document, utilisez la syntaxe suivante : @name. Exemple : @CameronTrivedi2013. A la compilation du document, la référence bibliographique citée sera mise en forme dans le texte et sera automatiquement ajoutée en fin d’article.

Documentation officielle : https://quarto.org/docs/authoring/citations.html

7. Glossaire

Pour que l’ensemble de la démonstration soit accessible pour un large public de SHS, vous pouvez vous appuyer sur un glossaire pour définir ou préciser certains termes. Pour cela, utilisez le système de note de bas de page proposé par Quarto. Voici la syntaxe markdown à utiliser :

Voici un terme bien technique qui mériterait quelques précisions [^1] et
un second référence [^2]

[^1]: Voici la définition du premier terme

[^2]: Et le second

Cela donne : Voici un terme bien technique qui mériterait quelques précisions ¹ et un second référence ²

A la compilation du document, la note sera automatiquement ajoutée dans la section Glossaire de l’article. Exemple

Documentation officielle : https://quarto.org/docs/authoring/markdown-basics.html#footnotes

8. Longueur de l’article

Le code source d’un article ne peut dépasser 85000 caractères (texte + code). Pour calculer le nombre de caractères d’un document Quarto, vous pouvez utiliser la fonction txtcount() du package rmdwc :

```{r}
options(scipen=999)
library(rmdwc)
files <- txtcount("index.qmd")
files$chars
```

9. Besoin d’aide ?

Si vous rencontrez des difficultés dans la construction technique de votre article exécutable, n’hésitez pas à contacter le comité éditorial : contact[a]rzine.fr

Glossaire

Voici la définition du premier terme ↩
Et le second ↩