Rmarkdown avec conditions pour créer des pdf et html en différentes langues et avec des images

“Knit” avec plusieurs options de rendu

Mes documents rmarkdown sont créés en différentes langues (français et anglais). Je fais aussi en sorte que le rendu final soit similaire entre une sortie pdf et une sortie html. De cette manière, je peux utiliser la sortie html pour la version électronique de mes formations et proposer une version papier à partir du pdf. Par ailleurs, j’ai aussi une version (partielle) des codes R pour les étudiants et une (qui marche) pour le formateur. Ces codes R sont produits à partir de la feuille de route rmarkdown qui passe par la commande “purl”. Cela signifie que j’ai plusieurs options qui sont inclues dans un unique document rmarkdown. Utiliser un unique document me permet d’apporter les modifications et mises à jour de mes formations dans le même fichier. Je n’ai pas besoin de me balader entre différents documents pour m’assurer que les mises à jour ont été apportées partout dans les feuilles de route et les scripts R. En règle générale, j’utilise un script R dit “run-all” qui permet de choisir les différentes options pour produire les différentes versions html, pdf, script R étudiant et formateur (que l’on peut mettre dans une boucle “for”).

Une liste non exhaustive

Dans les fichiers de sorties ci-dessus, je liste différentes astuces que je dois utiliser pour rendre ces différentes versions possibles ainsi que quelques bonus:

• Utilisation des options des “chunks” pour produire les textes en fonction de la langue choisie,
• Utilisation de fonctions pour formater ou colorer du texte et son arrière-plan, de manière similaire en pdf ou en html,
• Afficher des images dans le texte en fonction de la langue choisie,
  • Afficher deux images côte à côte et centrée sur la page en html et en pdf,
• Colorer l’arrière plan d’une zone de code créée avec un environement “verbatim”,
• Sortir d’un fichier rmarkdown le code R des “chunks” pour vos formations, avec une version différente entre le formateur et les participants.

Je modifirai la liste si je fais face à de nouvelles difficultés ou si je trouve de meilleures manières de faire les choses.

Fichiers de sortie en pdf, html, français et anglais

La liste complète de mes astuces rmarkdown se trouve dans les fichiers qui suivent (affichés en iframe). Les fichiers Rmd et les fichiers complémentaires, nécessaires à la création de ces documents PDF et HTML pour chaque langue, se trouvent ici sur mon github.

• HTML version anglaise
• HTML version française
• PDF version française et PDF version anglaise sont sur le github

Une librairie à utiliser avec précaution

Les fonctions de formattage utilisées dans le document Rmd présenté dans cet article sont dans un package R dans le dossier de mon compte github. Cependant, ces fonctions doivent être utilisées avec précaution car elles doivent être utilisées avec des fichiers externes à appeler lors de la construction de votre document : un fichier tex à mettre dans “in_header” pour les PDF, et un fichier css pour les sorties HTML. La documentation n’est pas faite. Le guide d’utilisation se trouve dans les liens du paragraphe précédent. Vous pouvez installer cette librairie de cette façon:

# Library in development to be use with external customized header or css file
devtools::install_github("statnmap/Rmarkdown_tips")
library(KnitFmt)

Exemple: Inclure des sorties R dans des “chunks” conditionnels

    ```{r CodeInChunkEN, echo=(lang == "EN"), eval=(lang == "EN"), results='asis'}
    cat(
    '### Example of title in a chunk
    #### Example of subtitle in a chunk
    - ', styleFmt("cat", "codecommand"), ' should be used with ',
    styleFmt("sep = \"\"", "codecommand"), ' otherwise a space will be added
    before "##subtitle", which avoid it to be recognised as a subtitle in markdown.
    - ', styleFmt("eval", "codecommand"), ' can be used with R object to knit
    chunk specific to language. Here ', styleFmt("lang", "codecommand"),
    ' is ', lang,  '\n',
    '- Double space should work to define new paragraph, but when using R
    functions, it may require "\\\\n"
    _(Note the number of backslash in the code here to print "\\\\n" correctly...)_.
        + ', styleFmt("For instance when using the format function,
                      following two spaces won\'t work:", "advert"), '  ',
    '    + This sentence won\'t be on a new line.',
    sep = "")
    ```

Exemple: deux images côte-à-côte et centrées

    ```{r, echo=FALSE, out.width='25%', fig.align='default', results='asis'}
    beginCentering()
    knitr::include_graphics(paste0(figWD, "/fr.png"))
    cat("\vspace{1cm}")
    cat(" ")
    knitr::include_graphics(paste0(figWD, "/gb.png"))
    endCentering()
    ```

Exemple: Inclure du code markdown entre des commandes \begin et \end pour le format lateX

# Votre code rmarkdown pour une sortie en PDF uniquement
# % -- command for pandoc trick with \begin and \end -- %
\newcommand{\nopandoc}[1]{#1}

\nopandoc{\begin{}}
Votre texte avec _une syntaxe_ **markdown**
\nopandoc{\end}

# Sinon, utilisez mes fonctions beginStyleFmt et endStyleFmt
# avec cette astuce appelées dans le fichier "header" de votre document Rmd

Contenu

Version française complète en HTML

1. “Knit” avec plusieurs options de rendu
   • 1.1 Une liste non exhaustive
   • 1.2 Fonctions pour créer un rendu spécifique selon le format html ou pdf
2. Choisir une langue pour votre document

• 2.1 Inclure du texte dans des “chunks” au format ‘asis’
  • 2.1.1 Pour les titres et sous-titres au début du “chunk”
  • 2.1.2 Et les titres en milieu de “chunk” s’il y a une ligne vide avant
• 2.2 Inclure des sorties R dans les “chunks” conditionnels
  • 2.2.1 Exemple de titre dans un “chunk”
• 2.3 Images et chemins sous conditions
  • 2.3.1 Quand vos images sont dans un dossier défini et s’affichent dans un paragraphe différent du texte
  • 2.3.2 Quand vos images sont dans un dossier avec condition de langue et sont affichées en ligne dans le texte

3. Deux images côte-à-côte et centrées sur la page
4. Versions formateur et participants

• 4.1 Créer la feuille de route de la formation
  • 4.1.1 Exemple d’exercice
• 4.2 Extraire le code R du fichier rmarkdown

5. Essayez vous-même ce script !

• 5.1 Quelques limites

6. Astuces supplémentaires

@misc{Roche2017Rmark,
    author = {Rochette Sébastien},
    title = {Rmarkdown avec conditions pour créer des pdf et html en différentes langues et avec des images},
    url = {https://statnmap.com/fr/2017-03-11-rmarkdown-conditions-pour-creer-pdf-html-differentes-langues-et-images/},
    year = {2017}
  }