In larmarange/scdoc: Long document with R Studio, knitr, pandoc and prince XML

---

lang Langue du document au format ISO alpha 2, 'en' pour l'anglais, 'fr' pour le français

title Titre du document

author Auteur(s) du document (plusieurs entrées possibles)

date Date du document (au format AAAA-MM-JJ, pour générer automatiquement la date du jour, saisir '`​r format(Sys.time(), "%Y-%m-%d")`')

tags Mots-clés

abstract Résumé (doit commencer par | pour un résumé avec plusieurs paragraphes, ces derniers devant alors être indentés)

toc-title Titre de la table des matières

tof-title Titre de la table des figures

tot-title Titre de la table des tables

prefix-fig Préfixe pour la numérotation des figures (Figure par défaut)

prefix-table Préfixe pour la numérotation des tables (Table par défaut)

pdf Pour générer automatiquement un PDF avec Prince XML, cette option doit être égale à 'prince'

---

Autres paramètres de configuration {#config_autres}

Nous vous recommandons de placer au début de votre document le code suivant :

```{​r configuration, echo=FALSE, message=FALSE}
opts_chunk$set(
  comment = NA, # Ne pas afficher ## devant les résultats
  dev = "svg", # Graphiques au format SVG
  cache = TRUE, # Mise en cache
  fig.width = 8, fig.height = 6 # Taille par défault des figures
)
options(
  knitr.table.format = "html", # Tables directement au format HTML (kable)
  xtable.type = "html", # Tables en HTML (xtable)
  xtable.caption.placement = "top" # Titre avant le tableau (xtable)
)
knit_hooks$set(plot = hook_plot_html) # Figures directement au format HTML
windowsFonts(sans=windowsFont("Open Sans")) # Police par défaut des graphiques
```

Il s'agit de différentes options pour knitr. Les options passées via opts_chunk$set sont optionnelles. Libre à vous de les adapter en fonction de vos besoin. Pour les graphiques, nous avons priviliégié le format SVG car ce dernier permet un rendu de meilleur qualité dans le PDF produit tout en étant correctement interprété par les navigateurs modernes.

options(knitr.table.format = "html") et knit_hooks$set(plot = hook_plot_html) sont nécessaires pour une gestion adéquate des identifiants et des titres des tableaux et des figures (voir section et section pour plus de détails). Les options xtable.typeet xtable.caption.placement ne sont nécessaires que si vous utilisez le package xtable.

windowsFonts(sans=windowsFont("Open Sans")) est totalement optionnel. Cela permet de spécifier la polices de caractères à utiliser lors de la création de graphiques.

Format markdown

Dans la mesure où scdoc utilise pandoc pour interpréter le code mardown, il est possible d'utiliser tous les ajouts à markdown proposés par pandoc. Ces derniers sont décris en détails à http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown.

Il est également possible d'inclure directement du code HTML, qui sera conservé tel quel lors de l'export.

Titres et liens internes

Les titres sont automatiquement numérotés. Il est cependant possible de spécifier qu'un titre particulier ne doit pas être numéroté en lui ajoutant la classe CSS .unnumbered.

## Titre non numéroté {.unnumbered}

produira :

Titre non numéroté {.unnumbered}

Pour créer un lien interne vers un titre donné, il faut en premier lieu attribuer un identifiant unique à votre titre :

## Titre avec identifiant {#id_titre}

produira :

Titre avec identifiant {#id_titre}

Pour créer un lien interne, il suffit dès lors de cibler le titre désiré avec son identifiant.

Voir [section](#id_titre).

produira :

Voir section.

Vous remarquerez au passage que le numéro du titre a été automatiquement ajouté (ainsi que le numéro de page dans la version PDF).

Inclure des chunck R

Bloc de code

```{​r}
summary(cars)
```

produira

summary(cars)

Autre exemple :

```{​r}
summary(cars)
str(cars)
sum(cars$speed)
```

summary(cars)
str(cars)
sum(cars$speed)

Pour plus de détails, voir http://yihui.name/knitr/.

Code en ligne

Il est possible d'insérer du code R directement dans un paragraphe de texte avec :
`r​ ... some R code ... `

La somme de 3 plus 4 est égale à `r 3+4`.

produira

La somme de 3 plus 4 est égale à r 3+4.

Le résultat apparait comme faisant partie intégrante du texte.

Tableaux {#tables}

Les tableaux sont automatiquement numérotés. De même, une table des tables est générée automatiquement. Le préfixe des numéros de table et le titre de la table des tables peuvent être personnalisés (voir chapitre).

Plusieurs fonctions et package R permettent de produire des tableaux correctement formatés en HTML (voir ci-après). Pour chaque package, nous présenterons comment personaliser le titre du tableau et comment lui attribuer un identifiant. L'ajout d'un identifiant permet de réaliser un lien interne. Par exemple :

Voir [table](#exemple_kable).

produira

Voir table.

Fonction kable

Il vous faut une version récente de knitr afin que soit disponible l'argument caption. La dernière version de knitr peut-être installée avec la commande :

require(devtools)
install_github('knitr', 'yihui')

En premier lieu, il faut calculer un tableau (avec une fonction telle que table ou xtabs).

data(Titanic)
d <- as.data.frame(Titanic)
tab <- xtabs(Freq~Class+Survived, data=d)

Ensuite, on appellera la fonction kable dans un chunk ayant pour option results='asis' afin que le code produit par kable soit inclus tel quel. Il importe également que l'on ait précisé à knitr de produire les tableaux au format HTML (options(knitr.table.format = "html"), voir section).

Le paramètre caption (optionnel) permet d'indiquer un titre de tableau. Pour ajouter un identifiant, on utilisera le paramètre table.attr. Enfin, il est possible de spécifier l'alignement de chaque colonne avec align.

kable(tab, table.attr = 'id="exemple_kable"', 
      caption = "Tableau généré avec kable", 
      align = c('l','r','r'))

Package xtable

Le package xtable offre de multiples possibilités pour générer un tableau au format HTML. Il est recommandé de personnaliser au préalable les options xtable.type et xtable.caption.placement (voir section).

Comme pour kable, xtable sera appelée dans un chunk ayant pour option results='asis'. La syntaxe est la suivante :

require(xtable)
xtable(tab, caption="Tableau généré avec xtable", 
       label="exemple_xtable", 
       align=c("lrr"))

Package tables

Pour une gestion aisée du titre du tableau, une version récentes (0.7.67 ou plus) du package tables est requise. La dernière version peut être installée avec la commande :

install.packages("tables", repos="http://R-Forge.R-project.org")

Dans un premier temps, le tableau sera calculé avec la fonction tabular (voir l'aide de cette dernière pour plus de détails) :

require(tables)
tab2 <- tabular( (Species + 1) ~ (n=1) + Format(digits=2)*
         (Sepal.Length + Sepal.Width)*(mean + sd), data=iris )

Le tableau sera ensuite converti au format HTML avec la fonction html. Cette dernière sera appelée dans un chunk ayant pour option results='asis'. Petite particularité, le titre devra être indiqué avant d'appeler html avec la fonction table_options. Il est recommandé de remettre cette valeur à NULL juste après pour éviter d'impacter les tableaux suivants.

table_options(HTMLcaption = 'Tableau généré avec tabular et html') 
html(tab2, id='exemple_tabular')
table_options(HTMLcaption = NULL) 

Graphiques {#figures}

Selon la norme HTML 5, on aura recours à la balise <figure> pour inclure des graphiques ou d'autres médias. Une même figure peut contenir plusieurs graphiques. Le titre d'une figure sera indiqué avec une balise <figcaption>.

Les figures sont automatiquement numérotées. De même, une table des figures est générée automatiquement. Le préfixe des numéros de figure et le titre de la table des figures peuvent être personnalisés (voir chapitre).

Les balises <figure> et <figcaption> seront directements entrées dans le fichier markdown. (NB : cette approche fonctionnera sous réserve que l'option knit_hooks$set(plot = hook_plot_html) ait été appliquée au début du document, voir section.)

<figure id="exemple_fig">
```{​r, echo=FALSE}
plot(cars)
```
<figcaption>Titre de la figure</figcaption>
</figure>

produira

wzxhzdk:18

Titre de la figure

L'ajout d'un identifiant permet de réaliser un lien interne. Par exemple :

Voir [figure](#exemple_fig).

produira

Voir table.

Un graphique créé sans être encadré par une balise <figure> ne sera pas ajouté à la table des figures.

```{​r, echo=FALSE}
plot(table(rpois(100, 5)), type = "h", col = "red", lwd = 10,
     main = "rpois(100, lambda = 5)")
```

produira

plot(table(rpois(100, 5)), type = "h", col = "red", lwd = 10,
     main = "rpois(100, lambda = 5)")

Notes de bas de page

Ceci est un texte^[Avec une note de bas de page].

produira :

Ceci est un texte^[Avec une note de bas de page].

pandoc reconnait plusieurs syntaxes pour rédiger des notes de bas de page (voir http://johnmacfarlane.net/pandoc/README.html#footnotes pour plus de détails).

Équations

Il est possible d'écrire des équations au format LaTeX.

$\alpha+\beta=\gamma$
$$\int_0^\infty e^{-x^2} dx=\frac{\sqrt{\pi}}{2}$$

produira :

$\alpha+\beta=\gamma$ $$\int_0^\infty e^{-x^2} dx=\frac{\sqrt{\pi}}{2}$$

Les équations seront transformées au format MathML. Par ailleurs, s'il y a au moins une équation dans la page, la librairie MathJax sera chargée afin que les équations soient correctement rendues sur tous les navigateurs.

Ponctuation intelligente

L'option ponctuation intelligente de pandoc ^[http://johnmacfarlane.net/pandoc/README.html#smart-punctuation] est active. Cette dernière gère les points de suspensions (...), les tirets semi-cadratins (--), les tirets cadratins (---) et les guillemets anglais ("").

Par exemple :

--  ---   ...  "test"

produira

-- --- ... "test"

La ponctuation française n'est pas encore gérée mais pourra être ajoutée dans une future version.

Références bibliographiques

On peut ajouter une référence bibliographique au texte. Par exemple, le pacakge TraMineR permet d'analyser des séquences [@gabadinho:2011analyzing]. Pour plus de détails sur la syntaxe, voir http://johnmacfarlane.net/pandoc/README.html#citations.

Il faut soit que les sources bibliographiques soit ajouter au format YAML dans votre fichier R markdown.

Une autre option consiste à utiliser zotxt pour lier votre document à votre base Zotero. Pour cela, vous devrez ajouer l'option - zotxt:'yes' à votre YAML d'en-tête (voir section). Il importera également que Zotero soit ouvert lorsque vous lancer Knit HTML.

Enfin, vous pouvez utilisez la fonction zotxt2yaml pour extraire avec zotxt les références citées dans votre document et générer le YAML correspondant.

---

references:

title: Analyzing and Visualizing State Sequences in R with TraMineR id: gabadinho:2011analyzing issued: day: 7 month: 4 year: 2011 author: - given: - Alexis family: Gabadinho - given: - Gilbert family: Ritschard - given: - Nicolas - S. family: "Müller" - given: - Matthias family: Studer container-title: http://www.jstatsoft.org/v40/i04/paper type: article-journal ...

larmarange/scdoc documentation built on May 20, 2019, 7:57 p.m.