Warum ich rST Markdown vorziehe

Warum ich rST vorziehe

Ich werde nicht aufhören, das zu behaupten

• Ich habe die neue Version von "Logic for Programmers" v0.2 veröffentlicht. Diese Version enthält EPUB-Unterstützung, Constraint Solving und Inhalte zur Formatspezifikation.
• Auch das zweite Buch "Learn TLA+" habe ich mit Sphinx geschrieben. Sphinx verwendet ein eigenständiges Markup namens reStructured Text (rST).
• rST hat eine steilere Lernkurve als Markdown. Nachdem ich einige Bücher in Markdown geschrieben hatte, hatte ich das Gefühl, etwas Besseres zu brauchen, und bin zu rST gewechselt.

Warum rST besser ist

• Markdown ist eine leichtgewichtige Darstellung von HTML, während rST eine mittelschwere Darstellung eines abstrakten Dokumentbaums ist.
• So erstellt man in Markdown ein Bild:

  ![alttext](example.jpg)
  

• So erstellt man in rST ein Bild:

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

• rST ist erweiterbar. Man kann neue Textobjekte hinzufügen.
• Sphinx kann Cross-Referencing verarbeiten. Wenn man zum Beispiel in einem Dokument einen foo-Anker setzt und in einem anderen Dokument :ref:image <foo>`` einfügt, setzt Sphinx die richtige URL ein.
• Mit rST lässt sich Transformationscode zusammen mit dem Rest des Build-Prozesses konfigurieren.

Ein Anwendungsfall

• "Logic for Programmers" ist ein Buch mit mathematischem Schwerpunkt und braucht Übungsaufgaben für die Leser.
• Ich möchte Aufgaben und Lösungen im Dokument nebeneinander platzieren, aber für die Leser sollen die Lösungen hinten im Buch erscheinen.
• Dafür habe ich eine eigene Erweiterung für Übungsaufgaben geschrieben.

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

• In HTML werden Aufgaben und Lösungen inline gerendert.
• In EPUB und LaTeX werden die Lösungs-Knoten per Transformation unter solutionlist verschoben, und an jede Aufgabe wird ein Referenz-Knoten angehängt.

"Aber ich mag die Syntax nicht"

• Viele finden die Syntax von rST hässlich.
• Es ist nachvollziehbar, ein gutes Werkzeug nicht zu verwenden, wenn man die Syntax nicht mag.
• Es gibt auch andere Dokument-Builder wie asciidoc, MyST, Typst, Pollen oder pandoc-erweitertes Markdown.
• Markdown-basierte Dokumentgeneratoren fügen oft eigene Preprocessing-Schritte hinzu, um neue Anwendungsfälle zu unterstützen.
• Es gibt LSP und treesitter für Markdown und rST, aber nicht für gitbook-markdown, md-markdown oder leanpub-markdown.

Nächste Woche kein Newsletter

• Ich werde in Hongkong sein.

Update 2024-07-31

• Ich habe eine kurze Beschreibung von "Logic for Programmers" hinzugefügt.
• Das Buch behandelt, wie formale Logik in der alltäglichen Softwareentwicklung nützlich sein kann.
• Es enthält einen grundlegenden mathematischen Überblick und acht verschiedene Anwendungen.
• Es befindet sich noch in der Alpha-Phase, umfasst aber bereits mehr als 20.000 Wörter und enthält schon viele nützliche Inhalte.

Zusammenfassung von GN⁺

• rST ist ein leistungsfähigeres Werkzeug zum Schreiben von Dokumentation als Markdown.
• In Kombination mit Sphinx bietet es die Möglichkeit, Dokumentbäume zu transformieren und zu erweitern.
• Das ist nützlich beim Schreiben von Büchern wie "Logic for Programmers".
• Viele halten die Syntax von rST für hässlich, aber es gibt auch andere Alternativen.
• Für Menschen mit Interesse an Softwareentwicklung im Zusammenhang mit formaler Logik kann das nützlich sein.

[GN⁺]

Hacker-News-Kommentare

• Der größte Vorteil von Markdown ist, dass es leicht zu lesen und leicht zu schreiben ist
• Markdown ist vielleicht nicht das optimale Werkzeug, um Bücher zu schreiben, aber es ist optimal, um schnell formatierten Text zu verfassen
• Für das Schreiben von Büchern würde man LaTeX verwenden; Markdown eignet sich für Notizen, schnelle Dokumentation und Kommentare
• reStructuredText (reST) ist für sich genommen etwas rau, aber in Kombination mit Sphinx sehr gut
  • Sphinx ist eine gute Wahl für große, professionelle Dokumentationsseiten
  • Sphinx ermöglicht es, gemeinsame Elemente der Website einfach anzupassen
  • Es stellt sicher, dass interne Links immer aufgelöst werden
  • Es verfügt über eine klar definierte Erweiterungs- und Theme-API
  • Auf PyPI gibt es eine Vielzahl von Erweiterungen und Themes
• Markdown ist eine leichtgewichtige Darstellung von HTML, während reST eine mittelschwere Darstellung eines abstrakten Dokumentbaums ist
• Markdown wurde entwickelt, um formatierten Text aus E-Mail-Nachrichten und Usenet-Beiträgen umzuwandeln
• reST-Werkzeugen fehlt die Fähigkeit, RST-Dateien automatisch zu erzeugen
• Markdown ermöglicht es, einfache Aufgaben schnell zu erledigen, und bei Bedarf rohes HTML einzubetten
• MyST bietet die Funktionen von reStructuredText und erlaubt zugleich die Verwendung der Markdown-Syntax
• Die Dokumentation auf GitHub-Projektseiten kann komplex sein, und es kann nützlich sein, Sphinx und Markdown gemeinsam zu verwenden
• Der Autor erwähnt rST im Zusammenhang mit dem Satz seines eigenen Buches
• reST ist kein Konkurrent zu MarkDown, sondern ein Format, das vor MarkDown entstanden ist
• Markdown und reST verfolgen im Grunde dasselbe Ziel
• Sowohl Markdown als auch reST sind gut lesbar und schnell zu schreiben
• Markdown hat sich aus historischen Gründen stärker verbreitet
• Markdown kann benutzerdefinierte Blocktypen definieren und den Dokumentbaum transformieren
• Jupyter Book ist ein gutes Beispiel dafür, dass man mit Markdown in andere Ziele wie PDF rendern kann