Introduction

Ce livre est un travail personnel.

J’ai choisi de le publier et de le partager pour « faire ma part ».

La consultation de ce livre est « en don libre ».

Oui, vous pouvez

Si vous souhaitez m’encourager ou m’aider, vous pouvez.

• effectuer un don.
  • Il vous suffit de me contacter (https://marcjestin.fr), je vous dirai comment faire.
• me proposer un travail rémunéré salarié (pas nécessairement en informatique)
  • sédentaire
  • en télétravail
  • ou dans un bureau,
  • temps partiel ou temps plein,
  • courte durée ou plus long terme.

Mes sites concernant Rust et mdBook

Rust

• Apprendre et maîtriser Rust
• Apprendre Rust par l’exemple
• Rust en vrac
• Trucs et astuces Rust

mdBook

• Apprendre et maîtriser mdBook
• Améliorer mdBook

Bonne lecture

Si vous rencontriez des erreurs, si vous souhaitiez suggérer des ajouts, ou pour toute autre démarche constructive et pertinente, n’hésitez pas à me contacter.

Merci.

Marc JESTIN,
éco-citoyen du monde
https://marcjestin.fr

Avertissement

Ce livre mdbook est à l’étape du projet de création et dans son format brouillon (draft) pour le moment.

Il peut comporter des défauts ou des erreurs et sa forme comme son contenu évoluent continuellement.

Merci de votre compréhension.

Si vous souhaitez m’apporter votre soutien ou votre concours pour ce projet, vous pouvez me contacter.

Marc JESTIN
éco-citoyen du monde
https://marcjestin.fr

Conseils de lecture

Ce livre est réalisé avec mdbook, l’outil de documentation de la communauté Rust.

Zoom d’affichage

Les sites web modernes ont la fâcheuse habitude de gaspiller de l’espace disponible et d’user nos organes visuels prématurémement.

Je vous recommande vivement de régler le zoom d’affichage pour un confort optimal.
Niveau de zoom à mon avis confortable :

• 150 % pour un moniteur 1920 x 1080 ;
• 180 % pour un moniteur 2560 x 1440 ;
• 240 % pour un moniteur 3840 x 2160.

Nos yeux et nos oreilles sont précieux (et les dégâts que nous leur causons sont irréversibles) :
PRÉSERVONS-LES !

Lecture à deux niveaux

Vous croiserez parfois des blocs comme celui-ci :

Nota :

• Cliquez sur le bloc « Compléments de lecture (avancés) » pour le développer.
• Cliquez à nouveau pour le réduire.

Mode d’emploi de mdBook

Utilisation des outils de mdbook

Prenez le temps d’interagir avec les espaces de ce site pour savoir ce que vous pouvez faire.

Avec la souris ou un écran tactile :

• parcours rapide
  • « aller à la page suivante dans le livre » (flèche sur le côté droit) ;
  • « revenir à la page précédente dans le livre » (flèche sur le côté gauche) ;
• options de l’interface
  • masquer / afficher la barre latérale (hamburger) ;
    • vous pouvez aussi redimensionner la barre latérale ;
  • modifier le thème d’affichage (pinceau) ;
  • rechercher (loupe) ;
• imprimer
  • vous pouvez produire une version imprimable du contenu de l’ensemble de ce livre (imprimante à droite).
    • que vous pouvez enregistrer au format pdf pour le parcourir hors connexion par exemple.
      • en perdant toutefois toute l’interactivité des blocs de code…

Parcours avec clavier

Il est possible de parcourir la plupart des éléments d’un livre mdBook « au clavier » :

• les touches flèche gauche et flèche droite permettent de passer d’une page à l’autre ;
• les touches flèche bas et flèche haut permettent de descendre ou remonter lentement dans la page en cours ;
• la touche Page bas permet de descendre d’un bloc correspondant à la hauteur affichée ;
• la touche Page haut permet de faire l’inverse ;

Recherche avec clavier

La recherche est accessible via le clavier :

• s : ouvre recherche et place le curseur dans la zone de saisie.
• Échappement : Ferme la recherche (conserve le contenu de la saisie).
• Flèche Bas / Flèche Haut : navigue dans les résultats proposés.
• Entrée : Ouvre le résultat surligné.

Mode d’emploi avancé de mdBook

Blocs de codes

Cette partie concerne plus particulièrement les lecteurs·trices des livres relatifs au langage Rust (moins ceux·celles de mon livre au sujet de mdBook lui-même).

mdBook permet de disposer d’un outil avec des blocs de codes Rust interactifs riches.

Tous les blocs de codes sont copiables directement ou avec le bouton ad hoc.

Nous pouvons en plus (options disponibles en fonction des paramètres choisis par l’auteur·trice) :

• les éditer (modifier) en nous plaçant dans le code et en supprimant ou saisissant du code ;
  • un bouton permet de remettre le code dans son état d’origine si besoin ;
• les compiler (ou obtenir les messages d’avertissement et d’erreur du compilateur) et / ou
• lorsque c’est prévu pour, observer leurs produits d’exécution (affichages console) ;
• afficher / masquer certaines parties du code.

Dans mes livres, lorsque des codes comportent des exemples d’erreurs qui ne passent pas à la compilation, ces parties sont commentées.
Décommentez-les, cliquez sur le bouton pour compiler et / ou exécuter, et lisez les retours du compilateur que vous obtenez à l’écran.

Lorsque cela est permis, vous pouvez également tout à loisir modifier le code et faire vos propres essais.

Exemple

Exercez-vous avec ce bloc simple :

• retirez les // à gauche de x += 1; puis
• cliquez sur « Run this code » (flèche « play ») pour compiler et tenter d’exécuter le code.
• Cliquez sur le bouton pour rétablir le code (Undo changes) puis
• cliquez sur « Run this code » (flèche « play ») à nouveau.

fn main() {
    let x = 7;
    // x += 1;  // Erreur à la compilation
}

Et avec ce bloc-ci :

• cliquez sur « Show hidden lines » (œil) pour afficher les lignes de code masquées ;
• cliquez à nouveau pour les masquer.
• exécutez le code.

use std::any::type_name;
use std::fmt::Display;

fn print_type_of<T: Display>(x: &T) {
    println!("Type of {x} : {}", type_name::<T>());
}

fn main() {
    let x = 7;
    print_type_of(&x);
    println!("{x}");
    println!("{x:?}");
    let x = x.to_string();
    print_type_of(&x);
    println!("{x}");
    println!("{x:?}");
}

Nota : les boutons interactifs apparaissent

• lorsque nous survolons le bloc de code avec notre souris ou
• lorsque nous touchons l’écran une première fois dans la zone du bloc de code (écrans tactiles de tablettes et d’ordiphones).

Seuls les boutons des actions autorisées sur le bloc de code concerné apparaissent.

Déception

Cela fait maintenant pas mal d’années que je suis le bébé, et je dois dire que je suis assez circonspect quant à ses capacités à appliquer des principes pourtant essentiels à mes yeux d’amélioration continue.

Pourtant, le dépôt officiel nous livre une belle promesse :

« mdBook is a utility to create modern online books from Markdown files. »
soit en français dans le texte :
« mdBook est un utilitaire permettant de créer des livres en ligne modernes à partir de fichiers Markdown. »

Alors, les enfants, il va falloir qu’on discute !
Vous et moi ne devons pas avoir la même notion de ce qui est moderne, je pense.

Ce qui est moderne, selon moi, dans le web et ailleurs :

• est multilingue avec une véritable localisation de l’ensemble de ses composantes publiques (visibles des utilisateurs·trices) du site web ;
• n’est PAS psychorigide et propose le LIBRE choix aux concepteurs des sites web quant à la manière dont leur création se comporte ;
• évolue et s’améliore rapidement dans le temps et, s’il est acceptable qu’un produit moderne ne fournisse pas tout dès sa sortie, tout du moins, le produit moderne vit un cycle d’amélioration continue, de préférence rapide.

Stratégie de gestion

Nous avons plusieurs possibilités pour réagir face à cela, dont voici quelques-unes seulement :

• éviter le produit et passer à autre chose ;
• au contraire, pour différentes raisons, préférer ce produit, et faire avec tel qu’il est ;
• signaler les bogues et proposer des améliorations dans les tickets (issues) du gestionnaire de dépôt ;
• regarder si le produit dispose de mécanismes licites, prévus dans sa conception, pour l’améliorer et l’ajuster à nos besoins ;
• faire de même coûte que coûte, quitte à sortir des sentiers battus ;
• prendre son courage à deux mains et participer au développement du produit pour pouvoir, qui sait, finir par convaincre les autres développeurs·ses et / ou proposer nous-même les correctifs qui, peut-être, seront finalement acceptés et intégrés dans le produit.

Un projet singulier

J’ai longtemps choisi une attitude personnelle composée d’un mélange d’ermitage silencieux et de la première option : ignorer et laisser tomber le produit et tracer ma route ailleurs.

J’ai finalement choisi de changer de posture après plusieurs sessions d’auto-apprentissage ou d’auto-perfectionnement en langageS de développement, de veille et de projets personnels : dorénavant, je vais m’investir plus lourdement sur le langage Rust et, par voie de conséquence, mdBook qui fait partie de son écosystème de premier rang.

L’un et l’autre sont intéressants et apportent des choses très utiles.
L’un et l’autre sont perfectibles.
L’histoire n’est pas construite à l’avance.
Chacun·e d’entre nous peut apporter sa pierre, à sa façon, avec sa personnalité, ses valeurs…

J’ai choisi de prendre le temps de rédiger et de publier des supports, qui, je l’espère, aideront d’autres que moi à mieux comprendre, apprendre et maîtriser Rust et mdBook.

J’y passe quelques messages…
Qui sait s’ils seront entendus…

Si vous souhaitez apporter votre contribution à ce livre, n’hésitez pas : contactez-moi ! (via mon site)

Marc JESTIN
éco-citoyen du monde
https://marcjestin.fr

Modification des feuilles de style mdBook

Les manipulations décrites ici et dans les sous-chapitres sont parfaitement licites et prévues par mdBook.
La documentation nous indique que :

« Le thème est totalement personnalisable, vous pouvez remplacer sélectivement chaque fichier du thème par le vôtre en ajoutant un dossier theme/ à côté du dossier src/ à la racine de votre projet. » ¹

Le compilateur mdBook fonctionne sur le principe de la surcharge :

• Si nous avons défini un fichier, par exemple theme/css/general.css, alors le compilateur s’appuie sur ce fichier pour construire le site web mdBook cible.
• Sinon, le compilateur mdBook utilise son fichier de base.

Nous disposons d’une autre surcharge que nous traitons dans Définition de styles CSS personnalisés dans mdBook.

Récupération des feuilles de styles d’origine

Les feuilles de styles font partie des thèmes mdBook.

Pour récupérer une copie des fichiers d’origine, nous pouvons, en nous plaçant dans le dossier racine de notre projet mdBook, utiliser la commande :

mdbook init --theme temp # temp ou un autre nom de dossier qui n'existe pas

La commande crée cette arborescence de fichiers :

temp
├── book
├── book.toml
├── src
│   ├── chapter_1.md
│   └── SUMMARY.md
└── theme
    ├── book.js
    ├── css
    │   ├── chrome.css
    │   ├── general.css
    │   ├── print.css
    │   └── variables.css
    ├── favicon.png
    ├── favicon.svg
    ├── fonts
    │   ├── fonts.css
    │   ├── OPEN-SANS-LICENSE.txt
    │   ├── open-sans-v17-all-charsets-300italic.woff2
    │   ├── open-sans-v17-all-charsets-300.woff2
    │   ├── open-sans-v17-all-charsets-600italic.woff2
    │   ├── open-sans-v17-all-charsets-600.woff2
    │   ├── open-sans-v17-all-charsets-700italic.woff2
    │   ├── open-sans-v17-all-charsets-700.woff2
    │   ├── open-sans-v17-all-charsets-800italic.woff2
    │   ├── open-sans-v17-all-charsets-800.woff2
    │   ├── open-sans-v17-all-charsets-italic.woff2
    │   ├── open-sans-v17-all-charsets-regular.woff2
    │   ├── SOURCE-CODE-PRO-LICENSE.txt
    │   └── source-code-pro-v11-all-charsets-500.woff2
    ├── highlight.css
    ├── highlight.js
    └── index.hbs

Les thèmes comportent :

• des feuilles de styles ;
• une favicon ;
• des polices de caractères au format woff2 ;
• un fichier index.hbs.

Nous ne traitons que des feuilles de styles dans cette section, mais nous copions l’intégralité du dossier theme/ à la racine de notre projet tout de même. Cela pourra toujours servir… 😉

Nous pouvons maintenant supprimer le dossier temp/ qui ne nous sert plus à rien.

Défrichage

Il nous faut maintenant défricher pour savoir qui fait quoi dans cette architecture de fichiers.

• ``theme/css/` « est le dossier contenant les fichiers CSS pour le style » ² :
  • css/chrome.css : gère les éléments de l’interface utilisateur.
  • css/general.css : définit les styles de base.
  • css/print.css : définit les styles pour l’impression.
  • css/variables.css : contient les variables utilisées dans les autres fichiers CSS.

Ce fichier n’est pas dans le dossier CSS (?!). Il est dans theme/ tout court, à côté du fichier JavaScript qui va avec. Il s’agit de la feuille de styles pour la coloration syntaxique des blocs de code :

• highlight.css

Ce fichier non plus n’est pas dans le dossier CSS ! (Décidément !) Il s’agit du fichier de déclaration des polices utilisées, et il est avec les polices en question dans le dossier theme/fonts :

• fonts/fonts.css. ³

Au boulot !

Clairement, pas mal de choses ne vont pas du tout dans les feuilles de styles proposées par mdBook par défaut.

Par exemple, si nous utilisons des zones extensibles (<details>) dans nos pages mdBook, celles-ci ne sont pas développées lorsque nous créons la version imprimable du livre. Dommage, Éliane !

1. https://github.com/rust-lang/mdBook/blob/master/guide/src/format/theme/README.md ↩

2. Je cite la documentation qui, sur quelques lignes, nous livre une superbe démonstration de dissonance cognitive. ↩

3. Quand on commence à défricher un code source et que l’on s’aperçoit de telles dissonances cognitives, on peut commencer à s’inquiéter quant à la qualification et la santé mentale des développeurs·ses qui l’ont produit… De mon point de vue. ↩

Agrandissement général

Sauts de lignes automatiques dans les blocs de codes

Impression

Intégration des zones extensibles () dans la version imprimée

Définition de styles CSS personnalisés dans mdBook

Utilisation de codes JavaScript pour améliorer mdBook

Préprocesseurs pour mdBook

mdBook prévoie un mécanisme de type crochets (hooks) comme le font beaucoup d’outils modernes.

Support de <details> dans mdBook (CommonMark)

Lisez cette page jusqu’au bout : c’est… croustillant à souhait !

mdBook n’a pas prévu de développer les blocs <details> dans la version impression (print) de ses feuilles de style par défaut.

Ont-ils·elles raison de faire ainsi ? Est-ce une décision réfléchie ou un oubli ?

Toutes les balises HTML sont rendues en l’état

mdBook s’appuie sur CommonMark comme indiqué dans sa documentation officielle qui nous renvoie vers le guide Markdown https://www.markdownguide.org/ que je recommande à tous·tes ceux·celles qui souhaitent savoir comment se servir de Markdown dans sa variante CommonMark. ¹

CommonMark fait clairement référence à l’utilisation de code HTML « brut » ou « natif » (raw HTML) dans sa documentation officielle, au chapitre 6.6 : ²

« 6.6 HTML brut

Le texte entre < et > qui ressemble à une balise HTML est analysé comme une balise HTML brute et est rendu en HTML sans échappement.

Les noms de balises et d’attributs ne sont pas limités aux balises HTML actuelles, de sorte que des balises personnalisées (et même, par exemple, des balises DocBook) peuvent être utilisées. »

Clairement, le HTML est supporté et « véhiculé » au travers du parseur Markdown, et c’est une excellente chose.

Voir aussi : Le parseur Markdown utilisé par mdBook est pulldown-cmark

mdBook n’est pas responsable de prévoir tous les usages

mdBook n’est pas explicitement responsable de prévoir tous les usages que nous faisons du HTML dans nos projets mdBook.

Et ils·elles ont clairement choisi de NE PAS se fatiguer.

C’est la raison pour laquelle on ne trouve aucune référence CSS à cette balise HTML <details> dans les feuilles de styles de mdBook.

Ils pourraient le faire et se montrer brillant·e·s et attentionné·e·s

Cela dit, <details> est une balise bien connue du HTML et il n’est pas difficile de prévoir un comportement natif dans une feuille de styles à son sujet.

Ce serait une excellente idée, et une excellente chose, que de l’intégrer de base dans les feuilles de styles

• pour l’affichage à l’écran (screen) et
• pour l’affichage dans la version du livre mdBook pour impression (print).

En attendant, nous pouvons le faire nous-mêmes

En attendant, nous pouvons le faire nous-mêmes, comme beaucoup d’autres choses qui sont proposées dans ce livre mdBook.

Pris en flagrant délit

Je note au passage que nos ami·e·s de mdBook se sont tiré une balle dans le pied sans doute sans s’en apercevoir dans LEUR PROPRE DOCUMENTATION.

En effet, dans la page au sujet des préprocesseurs de la documentation officielle mdBook, plus précisément à la fin du chapitre de page mdBook « Se greffer sur mdBook » (« Hooking into mdBook ») ³, ils·elles utilisent une balise <details> pour n’afficher un bloc de code source que si nous cliquons pour le voir.

Devinez ce qui se produit lorsque l’on recherche ce morceau de code dans la version « imprimée » (PDF) de la documentation officielle de mdBook…

1. https://rust-lang.github.io/mdBook/format/markdown.html?highlight=CommonMark#markdown ↩

2. https://spec.commonmark.org/0.31.2/#raw-html ↩

3. https://rust-lang.github.io/mdBook/for_developers/preprocessors.html#hooking-into-mdbook ↩

Le parseur Markdown utilisé par mdBook est pulldown-cmark

C’est une bibliothèque écrite en Rust qui implémente l’analyseur CommonMark. ¹

pulldown-cmark est développé sous forme d’un analyseur par flux (pull parser).

Où l’on parle de pulldown-cmark

Dans la documentation mdBook, pulldown-cmark est abordé dans le chapitre pour les développeurs·ses décrivant le fonctionnement des préprocesseurs, dans le sous-chapitre « trucs pour développer un préprocesseurs » :

« The mdbook-markdown crate exposes the pulldown-cmark crate used by mdBook to parse Markdown. The pulldown-cmark-to-cmark crate can be used to translate events back into markdown text. » ²

« Le paquet (crate) mdbook-markdown expose le paquet pulldown-cmark utilisé par mdBook pour analyser le Markdown. Le paquet pulldown-cmark-to-cmark peut être utilisé pour traduire à nouveau ces événements en texte Markdown. »

Plus simplement, on retrouve pulldown-cmark dans la documentation du paquet (crate) mdbook-markdown :

« This crate provides functions for processing Markdown in the same way as mdBook. The pulldown_cmark crate is used as the underlying parser. This crate re-exports pulldown_cmark so that you can access its types. » ³

« Ce paquet (crate) fournit des fonctions pour traiter le Markdown de la même manière que mdBook. Le paquet pulldown_cmark est utilisé comme parseur sous-jacent. Cette caisse ré-exporte pulldown_cmark afin que vous puissiez accéder à ses types. »

Fonctionnement (pour les développeurs·ses)

L’analyse par « événements » (pull parsing)

Contrairement à d’autres parseurs qui créent un arbre complet du document en mémoire (DOM), pulldown-cmark découpe le document Markdown en un flux d’événements (stream of events).

Lorsqu’il lit un fichier source Markdown, il génère des signaux au fur et à mesure :

• Start(Heading(Level1)) : Début d’un titre de niveau 1
• Text("Mon super titre") : Le texte du titre
• End(Heading(Level1)) : Fin du titre
• Start(List) : Début d’une liste
• …

Le rôle des bibliothèques citées

• pulldown-cmark est le moteur de base qui transforme le code source Markdown en une série d’événements (flux).
• mdbook-markdown est la passerelle interne de mdBook. Elle nous donne un accès direct à ce moteur pour que nous puissions intercepter et modifier les événements à la volée.
• pulldown-cmark-to-cmark est l’outil inverse. Une fois que notre préprocesseur a intercepté et modifié les événements (par exemple en remplaçant un mot-clé ou en formatant un tableau), pulldown-cmark-to-cmark réassemble le résultat pour recréer un fichier texte Markdown.

La méthode par événements évite d’avoir à manipuler du texte brut avec des expressions régulières (Regex) complexes et risquées. Elle nous propose de manipuler des objets logiques (des titres, du texte, des liens).

1. https://github.com/pulldown-cmark/pulldown-cmark/ ↩

2. https://rust-lang.github.io/mdBook/for_developers/preprocessors.html#hints-for-implementing-a-preprocessor ↩

3. https://docs.rs/mdbook-markdown/latest/mdbook_markdown/ ↩

Plongée dans les méandres de mdBook

Organisation du dépôt officiel de mdBook

Le fait que mdBook ait choisi MICROSOFT Github.com pour héberger son dépôt principal n’est pas un bon indicateur à mes yeux.

La racine du dépôt officiel de mdBook est : https://github.com/rust-lang/mdBook.

La racine des éléments relatifs aux feuilles de styles CSS dans mdBook est : https://github.com/rust-lang/mdBook/tree/master/src/theme/css.

À propos

mdBook

Ce site est construit avec mdBook, l’outil de documentation externe de la communauté Rust.

Auteur

Je m’appelle Marc JESTIN.

J’ai 55 ans, je réside actuellement en FRANCE à SURGÈRES (17).

Pour en savoir plus ou pour me contacter, rendez-vous sur

https://marcjestin.fr

Mes sites au sujet de Rust et de mdBook

Rust

• Apprendre et maîtriser Rust
• Apprendre Rust par l’exemple
• Rust en vrac
• Trucs et astuces Rust

mdBook

• Apprendre et maîtriser mdBook
• Améliorer mdBook