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 GitHub : https://github.com/rzine-reviews/rzine-article-template

Vous pouvez le télécharger directement en archive ZIP en cliquant sur ce lien ou plus simplement en ligne de commande :

quarto use template rzine-reviews/quarto-template

Dans tous les cas, vous récupérez un répertoire contenant à minima les fichiers suivants :

un fichier YAML _quarto.yml, qui contient les métadonnées générales du document Quarto.
un fichier Quarto index.qmd, qui contient le code source de l’article.
Un fichier BibTeX references.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 dossier _extensions, contient des éléments de mise en page. Ne pas modifier.

2. Compiler le fichier

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.

Ouvrez le fichier index.qmd avec Rstudio. Cliquez sur 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. Par exemple, pour le compiler en format pdf :

quarto render index.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

Il n’y a pas d’en-tête (YAML) dans le fichier siurce de l’article (index.qmd).Les métadonnées générales de l’articles sont à saisir dans le fichier _quarto.yml.

---
title: Rzine
subtitle: "Articles méthodologiques mis en application avec R"
date: today
# date-modified: last-modified
author:
  - name: "Auteur·rice 1"
    url: "https://rzine.fr"
    affiliations:
      - name: "Etablissement 1"
        url: "https://xxxxx.fr"
    orcid: 0000-0000-0000-0000
  - name: "Auteur·rice 2"
    url: "https://rzine.fr"
    affiliations:
      - name: "Etablissement 2"
        url: "https://xxxxx.fr"
    orcid: 0000-0000-0000-0000
    
keywords: [Rzine, template, Quarto, method, R, reproductibility]
abstract: |
     Modéle de mise en page Quarto pour la revue Rzine, qui permet de publier sur des méthodes de SHS, mises en application avec R. Plus d'informations sur https://rzine.fr.
---

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
Une liste de mots clefs
Résumé court de la publication (50 mots maximum)

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. Utilisez le fichier readme.txt pour y renseigner les métadonnées.

6. Bibliographie

Les références bibliographiques utilisées sont à saisir en format BibTeX dans le fichier references.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. Notes de bas de page

Pour que l’ensemble de la démonstration soit accessible pour un large public de SHS, vous pouvez vous appuyer sur les notes de bas de page pour définir ou préciser certains termes. Pour cela, utilisez le système de footnotes 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

Rendu graphique :

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

Les notes sont automatiquement ajoutées dans la section Notes de bas de page en fin d’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

Notes de bas de page

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