Pourquoi je préfère rST à Markdown

Pourquoi je préfère rST

Je ne cesserai pas de défendre cette idée

• J’ai publié une nouvelle version de "Logic for Programmers" v0.2. Cette version inclut la prise en charge d’epub, la résolution de contraintes et du contenu sur les spécifications formelles.
• J’ai aussi écrit mon deuxième livre, "Learn TLA+", avec Sphinx. Sphinx utilise un langage de balisage particulier appelé reStructured Text (rST).
• rST a une courbe d’apprentissage plus raide que Markdown. Après avoir écrit plusieurs livres en Markdown, j’ai senti qu’il me fallait quelque chose de mieux et je suis passé à rST.

Pourquoi rST est meilleur

• Markdown est une représentation légère de HTML, tandis que rST est une représentation de poids intermédiaire d’un arbre de document abstrait.
• Voici comment créer une image en Markdown :

  ![alttext](example.jpg)
  

• Voici comment créer une image en rST :

  .. image:: example.jpg
     :alt: alttext
  

• rST est extensible. On peut y ajouter de nouveaux objets textuels.
• Sphinx peut gérer les références croisées. Par exemple, si vous placez une ancre foo dans un document et :ref:image <foo>`` dans un autre, Sphinx insère la bonne URL.
• Avec rST, on peut intégrer le code de transformation avec le reste du processus de build.

Un cas d’usage

• "Logic for Programmers" est un livre lié aux mathématiques, donc il a besoin d’exercices pour les lecteurs.
• Je veux placer les exercices et leurs solutions côte à côte dans le document, mais pour les lecteurs, les solutions doivent apparaître à la fin du livre.
• Pour cela, j’ai écrit ma propre extension d’exercices.

  .. in chapter.rst
  .. exercise:: Fizzbuzz
     :name: ex-fizzbuzz
     An exercise
     .. solution:: ex-fizzbuzz
        A solution
  .. in answers.rst
  .. solutionlist::
  

• En HTML, les exercices et les solutions sont rendus inline.
• En epub et en latex, une transformation déplace les nœuds de solution sous solutionlist et attache des nœuds de référence à chaque exercice.

« Mais je n’aime pas la syntaxe »

• Beaucoup trouvent la syntaxe de rST laide.
• Il est compréhensible de ne pas vouloir utiliser un bon outil simplement parce qu’on n’aime pas sa syntaxe.
• Il existe aussi d’autres générateurs de documents comme asciidoc, MyST, Typst, Pollen et pandoc-extended markdown.
• Les générateurs de documentation basés sur Markdown ajoutent souvent leur propre étape de prétraitement pour prendre en charge de nouveaux cas d’usage.
• Il existe des LSP et treesitter pour Markdown et rST, mais pas pour gitbook-markdown, md-markdown ou leanpub-markdown.

Pas de newsletter la semaine prochaine

• Je serai à Hong Kong.

Mise à jour du 2024-07-31

• J’ai ajouté une brève description de "Logic for Programmers".
• Le livre traite de la manière dont la logique formelle peut être utile dans l’ingénierie logicielle du quotidien.
• Il comprend un aperçu des mathématiques de base et huit applications différentes.
• Il est encore au stade alpha, mais plus de 20 000 mots ont déjà été écrits et il contient déjà beaucoup de contenu utile.

Résumé de GN⁺

• rST est un outil de rédaction documentaire plus puissant que Markdown.
• Utilisé avec Sphinx, il permet de transformer et d’étendre l’arbre documentaire.
• Il est utile pour écrire des livres comme "Logic for Programmers".
• Beaucoup trouvent la syntaxe de rST laide, mais il existe aussi d’autres alternatives.
• Cela peut être utile aux personnes intéressées par l’ingénierie logicielle liée à la logique formelle.

[GN⁺]

Avis Hacker News

• Le principal avantage de Markdown est qu’il est facile à lire et à écrire
• Markdown n’est peut-être pas l’outil optimal pour écrire un livre, mais il est idéal pour rédiger rapidement du texte mis en forme
• J’utiliserais LaTeX pour écrire un livre, tandis que Markdown convient à la prise de notes, à la documentation rapide et à la rédaction de commentaires
• reStructuredText (reST) est un peu brut en lui-même, mais devient excellent lorsqu’il est combiné à Sphinx
  • Sphinx est un choix adapté aux sites de documentation volumineux et professionnels
  • Sphinx permet de personnaliser facilement les éléments communs du site
  • Il garantit que les liens internes sont toujours résolus
  • Son API d’extensions et de thèmes est bien définie
  • Il existe de nombreuses extensions et thèmes sur PyPI
• Markdown est une représentation légère du HTML, tandis que reST est une représentation de poids intermédiaire d’un arbre de documents abstrait
• Markdown a été conçu pour convertir du texte formaté provenant de messages électroniques et de publications Usenet
• Les outils reST manquent de capacités pour générer automatiquement des fichiers RST
• Markdown permet d’accomplir rapidement des tâches simples et d’insérer du HTML brut si nécessaire
• MyST permet d’utiliser la syntaxe Markdown tout en offrant les fonctionnalités de reStructuredText
• La documentation des pages de projet GitHub peut être complexe, et il peut être utile d’utiliser ensemble Sphinx et Markdown
• L’auteur mentionne rST dans le contexte de la composition typographique de son propre livre
• reST n’est pas un concurrent de Markdown, mais un format apparu avant Markdown
• Markdown et reST ont fondamentalement le même objectif
• Markdown et reST sont tous deux faciles à lire et rapides à écrire
• Markdown s’est plus largement imposé pour des raisons historiques
• Markdown permet de définir des types de blocs personnalisés et de transformer l’arbre du document
• Jupyter Book est un bon exemple d’utilisation de Markdown pour produire d’autres formats de sortie, comme le PDF