Dans l’article précédent, nous avons vu les éléments de structuration de Markdown. Cette fois-ci nous abordons les éléments de contenu venant s’insérer dans le texte.
L’échappement de caractères
En R, il y a des caractères réservés, par exemple les guillemets (") servent à délimiter des chaines de caractères. Cependant une chaine de caractères doit pouvoir contenir elle-même un guillemet. Pour cela, il faut donner l’information à l’interpréteur de texte que le guillemet a un sens au niveau du langage (délimitateur de texte) ou est un élément du texte. Pour cela on utilise un « caractère d’échappement », c’est à dire un caractère qui signifie que le suivant n’a pas la valeur sémantique qu’attend le langage mais juste sa valeur de caractère. En R, ce caractère est la barre oblique inversée aussi appelée antislash ou backslash (\). On l’obtient sur PC avec la combinaison AltGr + 8 sur un clavier français et sur Mac par Alt + Maj + / .
Et bien en Markdown, c’est pareil ! Tous les caractères ayant une signification en Markdown doivent être échappés pour apparaitre dans la sortie si ils sont dans une position qui entrainerait leur interprétation. En particulier : <, >, {, }, [, ], (, ), _, &, -, ., !, |, ` et bien sûr \ (l’antislash lui-même).
Si je veux insérer le texte constituant la balise br sans qu'elle soit interprétée,
il faut que j'écrive \<br\> et non <br> (notez qu'on est passé à la ligne).
Mais c'est aussi possible si je veux écrire que 1 est inférieur à 2
et supérieur à 0 : 1 \< 2 et 1 \> 0.
Cependant, vu que cela n'a pas de sens, ce n'est pas obligatoire : 1 < 2 et 1 > 0.
Rappelez vous que nous avons déjà vu cet antislash devant \pagebreak. Là aussi il est utilisé pour signalé que le mot qui suit est à prendre en tant que commande et non de façon littérale.
Dans les faits, tapez librement votre texte et rajoutez l’antislash si il ne sort pas comme vous l’attendez.
Les éléments textuels
L’emphase
Dans un texte, on parle d’emphase lorsqu’on cherche à mettre en évidence une portion de texte. La plus connue est le gras, mais il y a aussi l’italique ou le souligné. Toutes ces aspects ont le même but, faire ressortir le texte. En HTML et dans la plupart des langages de structuration de texte cependant, l’aspect final du document se doit d’être déconnecté de sa représentation structurelle. Dans les faits, en HTML, il existe tant des balises d’aspect (<b>, <i>) que de structuration (<strong>, <em>) même si la pratique a imposée les premiers et la norme les seconds.
Markdown quant à lui utilise exclusivement un symbole pour marquer l’emphase : *. Un texte situé entre 2 groupes d’étoiles (*texte*) est mis en emphase. Il y a 3 niveaux d’emphase possible selon le nombre d’étoiles englobantes :
Je suis une emphase de *niveau 1*
Je suis une emphase de **niveau 2**
Et moi une emphase de ***niveau 3***
(qui est en fait une emphase de niveau 1 au sein d'une emphase de niveau 2)Le résultat à l’écran dépendra de la feuille de style appliquée à la page. Mais le code généré sera respectivement :
<p>Je suis une emphase de <em>niveau 1</em></p>
<p>Je suis une emphase de <strong>niveau 2</strong></p>
<p>Et moi une emphase de <strong><em>niveau 3</em></strong></p>C’est à dire du code sémantique (pas de <b> et de <i>). Avec les styles par défaut de Rstudio, le résultat est :
Et le souligné ?
Vous vous demandez comment générer du souligné ? Et bien on ne peut pas nativement en markdown ! En effet le code HTML <u> n’est plus théoriquement dans la norme (et <b> et <i> suivront probablement le même chemin à terme).
Cependant tout n’est pas perdu ! même si il n’y a pas de façon à-la-markdown d’écrire en souligné, il y a 3 moyens de le faire :
- Ecrire directement le code HTML englobant en utilisant
Je suis un texte <u>souligné</u>.. Les navigateurs HTML reconnaissent encore ce vénérable code, ou à défaut afficheront le texte non souligné si ils ne le reconnaissent pas. - Ecrire directement le code HTML en précisant le style :
Je suis un texte <span style = "text_decoration:underline;">souligné</span>.. C’est la méthode actuelle pour le faire. - Ecrire le code HTML et un élément de style :
Je suis un texte <span class = "souligne;">souligné</span>et une classe CSS nommée soulignée.1
Dans les faits, je vous conseille d’éviter le souligné.
Le surligné
Il n’est pas un élément Rmarkdown par lui-même, mais sachez que vous pouvez utiliser la balise <mark> pour surligner un passage (malheureusement le raccourci markdown ==text== disponible sur certains compilateur n’est pas accessible avec Rmarkdown). Il faut donc écrire :
Je suis un passage <mark>surligné</mark>.Les liens
Bien que vous en aurez rarement besoin, on peut ajouter des liens vers des sites internet via :
[texte du lien](https://example.com/adresse.du.lien)Mais vous pouvez aussi les utiliser pour faire des liens internes vers les entêtes via :
# L'entête concernée {#enteteconcernee}
[Lien vers l'entête](#enteteconcernee)Enfin il est possible de mettre un texte en « infobulle » (c’est à dire qui s’affiche lorsqu’on maintient la souris dessus sans cliquer) en le précisant à la suite de l’adresse entre guillemets :
[texte du lien](https://example.com/adresse.du.lien "texte de l'infobulle")Les images
Dans notre exercice, l’intégration d’image est rare car nous utilisons plutôt des graphiques générés directement par le code R. Toujours est-il, cela peut être intéressant pour intégrer un logo par exemple. Le format d’insertion est simple, c’est le même qu’un lien internet en rajoutant un point d’exclamation devant :
On peut poser un lien dessus en combinant :
[](https://example.com/adresse.du.lien)Il n’est pas possible facilement d’insérer une image « en dur » (par un copier-coller directement dans le code par exemple). Il faut impérativement passer par un lien web.
Les tableaux
La plupart de vos tableaux seront probablement créés par votre code R. Cependant ponctuellement, vous pourriez avoir besoin de créer manuellement des tableaux dans lesquels vous mettriez des données non tabulaires. Pour cela il faut dessiner le tableau avec des - (tirets-du-6, minimum 3 par « case ») et des | (pipe, AltGr+6 sur PC et Alt+Maj+L sous Mac).
Voici un tableau simple :
| Entête 1 | Entête 2 | Entête 3 |
|----------|----------|----------|
| Valeur 1 | Valeur 2 | Valeur 3 |
| Valeur 1'| Valeur 2'| Valeur 3'|
| Valeur 1"| Valeur 2"| Valeur 3"| ce qui donne avec la feuille de style par défaut :
Il est possible de changer l’alignement des colonnes en rajoutant des : sur la 2ème ligne selon de quel côté vous voulez aligner (ou de chaque côté pour centrer) :
| Entête 1 | Entête 2 | Entête 3 |
|:---------|:--------:|---------:|
| Valeur 1 | Valeur 2 | Valeur 3 |
| Valeur 1'| Valeur 2'| Valeur 3'|
| Valeur 1"| Valeur 2"| Valeur 3"| La colonne 1 est alignée à gauche, la 2 au centre et la 3 à droite :
A l’intérieur des « cases », les espaces ou le nombre de tirets est non significatif. On pourrait donc écrire :
| Entête 1 | Entête 2 | Entête 3 |
| :--- |:---:| ---:|
| Valeur 1 | Valeur 2 | Valeur 3 |
| Valeur 1'| Valeur 2'| Valeur 3'|
| Valeur 1"| Valeur 2"| Valeur 3"| Ce qui veut dire que si vous insérez du code R via `r ... `, vous pouvez tout à fait aligner pour que votre code soit lisible sans que cela n’ait d’impact sur le rendu. Voici par exemple un extrait de code source que j’utilise pour créer un petit tableau récapitulatif manuel :
| Indicateur | Valeur |
|:-------------------------------------------------------|-------------------------:|
| **nombre total de séjours chirurgicaux (hors EF)** | `r nSejours` |
| **nombre de séjours \< 24 heures (hors EF)** | `r nAmbu` |
| **Taux de chirurgie ambulatoire** | `r 100*nAmbu/nSejours` % |
| **Taux de chirurgie ambulatoire pour les gestes MSAP** | `r 100*nMSAPa/nMSAPt` % |Et les autres ?
Il existe d’autres balises markdown plus ou moins compatibles avec Rmarkdown mais nous avons vu les principales. Je vous laisserai les voir par vous même sur les nombreux sites qui présentent le langage (par exemple, https://markdownguide.org/cheat-sheet/ et tout le site autour si vous lisez l’anglais). Gardez à l’esprit que Markdown n’est pas une norme et que rien ne garantit l’exhaustivité du support et de la portabilité de tous les codes. Cependant ceux présentés ici sont utilisables avec Rmarkdown.
Conclusion
La prochaine fois nous verrons les blocs de code et rentrerons donc dans le vif du sujet.
- Si vous ne comprenez pas de quoi je parle, ignorez ! ↩︎