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 communiquerai mes coordonnées bancaires.
• me proposer un travail rémunéré salarié
  • sédentaire
  • en télétravail
  • ou dans un bureau
    • si ce n’est pas dans une grande agglomération
    • si c’est au Nord de la France (Bretagne, Normandie, Nord)
      • ou plus au Nord (l’Irlande me plairait tout particulièrement)
  • que vous soyez :
    • une entreprise ;
    • une administration ;
    • une association ou
    • un·e particulier·e.

Mes sites concernant 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 avec des patchs

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 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

Améliorer l’impression mdBook

Améliorer les blocs de code Rust dans mdBook

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

• 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 avec des patchs