Rédiger avec bookdown : pourquoi ? comment ?

{bookdown}, à quoi ça sert ?

• La documentation du package {bookdown} itself : https://bookdown.org/yihui/bookdown/
• Un bookdown sur la création de packages, écrit par Hadley Wickham et Jennifer Bryan: https://r-pkgs.org/
• Un bookdown pour créer des applications Shiny prêtes pour la mise en production rédigé par vos serviteurs chez ThinkR : https://engineering-shiny.org/
• Pour d’autres exemples, c’est par là : https://bookdown.org/home/archive/

• On ne se soucie pas de la composition du document
• Cela nous évite d’utiliser le langage LateX directement, has been et relativement compliqué quand on ne connait pas
• La collaboration autour de la rédaction s’en trouve largement simplifiée
• Les multiples formats de sorties possibles (PDF, HTML, Word)
• On peut également intégrer du contenu dynamique et interactif aux livre HTML

gitbook HTML : “Engineering Production-Grade Shiny Apps” rédigé avec {bookdown}

Votre premier bookdown

Avant de commencer

install.packages("bookdown")
library(bookdown)

devtools::install_github('rstudio/bookdown')
library(bookdown)

install.packages('tinytex')
tinytex::install_tinytex()

Création du nouveau book

--- 
title: "A Minimal Book Example"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
description: "This is a minimal example of using the bookdown package to write a book. The output format for this example is bookdown::gitbook."
---

• Un livre contient typiquement plusieurs chapitres. Ici, chaque fichier RMarkdown constitue un chapitre : 01-intro.Rmd, 02-literature.Rmd, etc. Par défaut, tous les RMarkdown sont pris en compte, dans l’ordre alphanumérique, excepté le fichier index.Rmd qui passe toujours en premier. Chaque fichier .Rmd doit commencer par un titre de niveau avec le nom du chapitre. Par exemple, le fichier 02-literature.Rmd commence par :

# Literature

• Le fichier _bookdown.yml est un fichier au format YAML contenant les métadonnées de notre livre. Si on souhaite faire apparaître seulement certains RMarkdown, ou dans un ordre différent, on l’indique dans ce fichier de la façon suivante :

rmd_files: ["index.Rmd", "03-method.Rmd", "01-intro.Rmd"]

• Le fichier _output.yml permet de définir les caractéristiques des formats de sortie. Vous avez noté que lorsqu’on rédige un fichier RMarkdown, on se pré-occupe uniquement du contenu. Pour la forme, elle est gérée à part, avec des fichiers de configuration spécifiques au format HTML, LateX pour une sortie PDF ou un fichier de styles Word. Vous pouvez notamment créer vos propres templates d’entreprise ou d’organisation pour tous les documents internes ou à diffuser, une bonne fois pour toutes ! Le fichier _output.yml permet donc d’ajouter les éléments de forme à nos pages, notamment une feuille de style css, ou encore du texte et des liens avant ou après la liste des chapitres :

bookdown::gitbook:
  css: style.css
  config:
    toc:
      before: |
        <li><a href="./">A Minimal Book Example</a></li>
      after: |
        <li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>

bookdown::render_book(
  input = "index.Rmd", 
  output_format = "bookdown::gitbook",
  output_dir = "docs")

Les bonus de {bookdown} par rapport à {rmarkdown}

• Créer des légendes pour vos graphiques et tables avec un formattage markdown. Dans le chunk qui crée votre table ou image, vous pouvez utiliser le paramètre fig.cap pour ajouter une légende. Lorsqu’on a de longues légendes de tables ou de graphes, ou lorsqu’on souhaite formatter le texte (e.g. texte en italique ou url), il est possible de rédiger en dehors du chunk avec la syntaxe markdown. Par exemple :

_Notez qu'il est nécessaire d'avoir une ligne vide au-dessus et en-dessous de la ligne où l'on écrit la légende._

(ref:maref) Un *scatterplot* des données `cars`

```{r foo, fig.cap='(ref:maref)'}
plot(cars)
```

• Faire référence à des chapitres, des figures et des tableaux dans le texte du document. Utiliser la notation {#titre} pour nommer la référence à un titre du document. Utiliser \@ref(titre) pour y faire référence dans le texte. Fonctionnez de la même manière pour faire référence à une figure en ajoutant le prefixe de label fig comme ci-dessous avec \@ref(fig:pression) :

## Titre précédent {#avant}
Du texte.

## Réferences 

Faites référence à la figure \@ref(fig:pression). 

Mais aussi au chapitre précédent (chapitre \@ref(avant)).

(ref:pressioncap) La légende du graphique.

```{r pression, fig.cap='(ref:pressioncap)'}
plot(pressure)
```

• numéroter et référencer les équations :

 
\begin{equation} 
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{equation} 

\@ref(eq:binom)

• écrire des théorèmes, lemmes, corrollaires, etc… qui sont numérotés :

```{theorem}
Ceci est mon théorème.
```

```{theorem, name = "Pythagore"}
Pour un triangle rectangle, si $C$ désigne la longuur de l'hypothénuse et
$A$ et $B$ la longeur des deux autres cotés, alors on a :
$$A^2 + B^2 = C^2$$
```

• de la même manière, écrire des preuves, remarques ou solutions, qui sont elles non numérotées, en utilisant respectivement proof, remark, et solution. L’intérêt de ces classes particulières c’est qu’elles peuvent être customisée spécifiquement dans une feuille de style adaptée.

```{css}
.remark {
color: red;
}
```
```{remark}
Voici notre remarque
```

Création de template PDF avec {pdfreport}