2.1 Installation

Le package est mis à disposition sur un depôt de l’organisation Rzine sur le GitLab Humanum.
Pour l’installer et le charger, exécutez les lignes suivantes :

# install.packages(remotes)
remotes::install_gitlab("rzine/package", host = "https://gitlab.huma-num.fr/", force = TRUE)
library(rzine)

2.2 Répertoire de travail

Avant de générer une fiche vierge, spécifiez un répertoire de travail.

setwd("/home/jeanne/Documents/Fiche_rzine")

2.3 Le template readrzine

Vous pouvez ensuite générer une fiche readrzine vierge en ligne de commande. Pour cela, copiez-collez les lignes de code suivantes, puis exécutez :

rmarkdown::draft(file = "index.Rmd", 
                 template = "readrzine", 
                 package = "rzine", 
                 create_dir = FALSE, 
                 edit = FALSE)

Cela génère un ensemble de fichiers (cf partie 2.5) à la racine de votre répertoire de travail :

2.4 Les fichiers associés

Certains fichiers sont à modifier (ou à remplir pour les sous-répertoires) en fonction du contenu de votre fiche :

2.5 Le R Markdown readrzine

Un fichier index.Rmd a été créé à la racine de ce nouveau répertoire :

Il s’agit du R Markdown à compléter pour rédiger une fiche. Ne modifiez en aucun cas son nom !

3.1 L’en-tête

L’en-tête d’un document R Markdown (parfois appelé YAML header) est délimité par deux lignes de pointillés et contient les métadonnées et les éléments de style du document.

Commencez par personnaliser l’en-tête du template readrzine vierge en modifiant le titre, le sous-titre, le.s nom.s de ou des auteur.es et les affiliations, exemple :

3.2 Le corps du document

Le corps d’un document R Markdown comprend deux types de blocs, que l’on peut alterner librement :

• Des blocs de texte brut mis en forme selon la syntaxe markdown
  
• Des blocs de code R (appelés *chunks) encadrés par les balises ` :
  • Ces chunks peuvent être nommés (recommandé)
  • De nombreuses options sur le comportement du chunk peuvent être spécifiées.

Ceci est du texte en *italique*, **gras** ou en ***Gras italique***.

Pour définir des listes à puces, utilisez les **tirets** :

- premier élément
- deuxième élément

Vous pouvez également ajouter des [liens cliquables](https://rzine.fr/) 

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

```{r}

x <- 37 + 12
print(x)

```

```{r nom_de_mon_chunck}

```

```{r nom_de_mon_chunck, echo = FALSE, warning = FALSE}

x <- 37 + 12
print(x)

```

3.3 Kniter un R Markdown

Vous pouvez générer (kniter) le R Markdown readrzine en format HMTL en ligne de commande ou depuis l’interface Rstudio.

Le fait de kniter (tricoter) un document R Markdown revient à le convertir dans un premier temps en format markdown puis (dans ce cas) en format HTML via Pandoc (logiciel libre de conversion de documents). Sur certains systèmes d’exploitation (comme Windows), il peut-être nécessaire d’installer Pandoc précédemment.

rmarkdown::render(".../Ma_fiche_Rzine/Ma_fiche_Rzine.Rmd", envir = new.env())

3.4 Quelques références

Pour en savoir plus et se former au Rmarkdown et à la syntaxe markdown :

• Cookbook R Markdown, de Y. Xie, C. Dervieux & E. Riederer
• R Markdown Definitive Guide, de Y. Xie, J. J. Allaire & G. Grolemund
• R Markdown for Scientists, de Nicholas Tierney
• Introduction à R et au tidyverse, de Julien Barnier
• Travail collaboratif avec R, de Lino Galiana
• Pimp my RMD: a few tips for R Markdown, de Yan Holtz
• R for Data Science, de H. Wickham & G. Groelemund
• Guide de la syntaxe R Markdown, de Rstudio
• guide de référence R Markdown, de Rstudio
• R Markdown Cheatsheet, de Rstudio
• Writing Reproducible Research Papers with R Markdown, de Resul Umit

4.1 Introduction & contextualisation

Une fiche doit obligatoirement contenir une introduction, qui explicite l’objectif, le contenu et les données utilisés. Si nécessaire, il est également demandé au auteure.s de contextualiser le contenu, autant sur le plan thématique que technique. N’hésitez-pas à ajouter des références dans la bibliographie.

Une fiche Rzine doit s’adresser à l’ensemble des disciplines de SHS et des sciences territoriales. Considérez que vos lecteur.rice.s ne seront pas forcément des spécialistes de la thématique ou méthode présentée !

4.2 Données utilisées

L’intégralité des données utilisées pour une fiche doivent :

• Être présentées et décrites dans la fiche.
  
• Être libre d’utilisation et de diffusion.
  
• Être mises à disposition des lecteur.rice.s, même si ces données sont déjà en libre accès.
  
• Être associées à des métadonnées qui permettent de retracer et comprendre ces données.
  
• Respecter le Règlement Général sur la Protection des Données.

Toutes les données chargées et utilisées dans une fiche devront être stockées dans le répertoire :

Chaque fichier de données ajouté doit être associé à un fichier de métadonnées !

4.3 Illustrations

```{r, echo=FALSE, fig.align='center', out.width = "15%"}

include_graphics("figures/folder_figures.png")

```

4.4 Bibliographie

Bien qu’il ne s’agisse pas d’une obligation, le template readrzine intègre automatiquement cette section. Si vous ne souhaitez pas afficher de bibliographie dans votre fiche, vous pouvez supprimer les lignes suivantes de votre R Markdown :

# Bibliographie {-}

<div id="refs"></div>

Si cette section vous intéresse, ne modifiez pas ces lignes. Il vous suffira de modifier/compléter les différentes références bibliographiques que vous souhaitez utiliser dans le fichier “biblio.bib” (format BibTeX), situé à la racine du répertoire :

Le template par défaut du fichier biblio.bib :

@Manual{R-base,
  title = {R: A Language and Environment for Statistical Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2020},
  url = {https://www.R-project.org/},
}

@Manual{R-knitr,
  title = {knitr: A General-Purpose Package for Dynamic Report Generation in R},
  author = {Yihui Xie},
  year = {2020},
  note = {R package version 1.28},
  url = {https://CRAN.R-project.org/package=knitr},
}

@Manual{R-rmdformats,
  title = {rmdformats: HTML Output Formats and Templates for 'rmarkdown' Documents},
  author = {Julien Barnier},
  year = {2021},
  note = {R package version 1.0.2},
  url = {https://github.com/juba/rmdformats},
}

Pour citer une références dans le corps du texte, utilisez la syntaxe suivante : [@Citation Key].
Par exemple [@R-base] affichera (R Core Team 2020) dans le corps du document.

Toutes les références bibliographiques présentes dans le fichier biblio.bib seront automatiquement ajoutées dans la section “Bibliographie”.

4.5 Informations session

Cette section obligatoire est directement intégrée au template :

## Infos session  {-}
  
```{r session_info, echo=FALSE}
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[1]], row.names = F))
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[2]], row.names = F))
```

Ne modifiez et ne déplacez pas cette section. Il s’agit de la première partie obligatoire des annexes.

Ce bout de code affiche des informations sur la session qui a permis de générer cette fiche (système d’exploitation, version de R et des packages utilisés). Voir l’exemple pour ce document.

4.6 Citation

Cette section obligatoire est directement intégrée au template :

## Citation {-}

```{r Citation, echo=FALSE}

rref <- bibentry(
   bibtype = "article",
   title = "Titre de la fiche",
   author = person("Auteur.e 1", "Auteur.e 2" ),
   journal = "Rzine.fr",
   publisher = "FR CIST",
   year = 2021,
   url = "https://...")

``` 

`r capture.output(print(rref))`

### BibTex : {-}

```{r generateBibTex, echo=FALSE}

writeLines(toBibtex(rref), "cite.bib")
toBibtex(rref)

``` 


<br/>

Ces deux chunks permettent l’affichage de la référence bibliographique de votre fiche dans le corps du document (Voir l’exemple pour ce document), ainsi que le stockage de cette référence en format BibTex, enregistrée dans le fichier cite.bib à la racine du répertoire.

Ne mofifiez pas cette section. Elle sera complétée avant publication par l’équipe éditoriale.

4.7 Glossaire

Cette section n’est pas obligatoire, cependant vos lecteur.rices ne seront pas forcément issus de votre discipline ou ne maîtriseront peut-être pas la thématique et/ou méthode présentée. Pour que l’ensemble de la démonstration soit compréhensible par un public large, vous pouvez utiliser la section “glossaire” pour définir certains termes utilisés dans la fiche.

Pour cela, il suffit d’utiliser la syntaxe markdown suivante dans le corps du texte :

Blabla bla bla bla bla mot à définir^[__Mot à définir__: Définition du terme... ect]

Au knit du document en format HTML, un numéro est associé et affiché après le “mot à définir”. Et ce mot et sa définition seront ajoutés dans la section glossaire.

Exemple : Mot à définir¹

Un lien interactif est alors automatiquement crée entre le “mot” dans le corps du texte et sa définition dans la section “Glossaire”.

Si vous ne souhaitez pas utilisez de “Glossaire”, vous pouvez supprimer ces lignes du template readrzine :

## Glossaire {- #endnotes}

<script type="text/javascript">

$(document).ready(function() {
  $('.footnotes ol').appendTo('#endnotes');
  $('.footnotes').remove();
});

</script>

5.1 Soumettre une fiche

Pour soumettre une fiche Rzine à évaluation, il est nécessaire de déposer l’ensemble du répertoire de la fiche sur un dépôt GitHub, puis de déployer le fichier HTML depuis celui-ci.

Exemple pour ce document :

1. L’ensemble du répertoire est mis à disposition sur ce dépôt (GitLab c’est pareil !).
   
2. Et le fichier HTML généré est consultable à cette URL.

Vous ne comprenez rien ? Vous comprenez mais vous ne savez pas du tout comment procéder ? Ne vous inquiétez pas, ce n’est pas si compliqué ! Et surtout, vous trouverez l’ensemble des explications et des étapes à réaliser dans ce document.

Une fois la mise à disposition de votre fiche sur GitHub, vous pouvez contacter le comité éditorial en envoyant l’URL du dépôt à contact@rzine.fr.

Une réponse vous sera envoyée dans les 10 jours. Si la structure de la fiche et de l’ensemble du répertoire attendu est respecté, un ou plusieurs relecteur.rice.s vous seront proposés.

5.2 Processus de relecture

L’intégralité du processus de relecture se fera sur GitHub par l’intermédiaire d’issues (voir de Pull-request pour les auteur.e.s les plus à l’aise avec Git).

Cela ne doit pas vous inquiéter… Comme pour l’étape de soumission, vous trouverez l’ensemble des explications et du processus à suivre dans ce document dédié.

5.3 Publication