Warum ich rST Markdown vorziehe

• Sphinx’ reStructured Text (rST) ist schwerer zu lernen als Markdown, macht es bei umfangreichen Dokumenten wie Büchern aber leichter, Struktur und Ausgabeformate präzise zu steuern
• Markdown ist eher eine leichtgewichtige Schreibweise für HTML, während rST rund um einen abstrakten Dokumentbaum Direktiven, Knoten und Renderer kombiniert, um neue Dokumentobjekte hinzuzufügen
• Sphinx transformiert den Doctree vor dem Rendering, sodass Aufgaben wie Querverweise, ausgabeformatspezifische Verarbeitung und Transformationen in bestimmten Build-Phasen innerhalb des Dokumentsystems behandelt werden können
• In Logic for Programmers werden Übungen und Lösungen nahe am Originaltext geschrieben; anschließend wird eine Custom Extension verwendet, die in EPUB- und LaTeX-Ausgaben Position und Darstellung ändert
• Einfaches Markdown bietet keine einheitliche Erweiterungssyntax und keine Unterstützung für Transformationen vor dem Rendering; je stärker Dokumentgeneratoren das mit separatem Preprocessing umgehen, desto schwächer werden Tool-Unterstützung und Erweiterbarkeit

---

Warum ich rST gewählt habe

• Die neue Version von Logic for Programmers ist mein zweites mit Sphinx geschriebenes Buch; auch meine frühere Arbeit, das neue Learn TLA+, nutzt Sphinx
• Sphinx verwendet reStructured Text, und rST hat eine steilere Lernkurve als Markdown
• Nachdem ich mehrere Bücher in Markdown geschrieben hatte, brauchte ich bessere Werkzeuge und wechselte zu rST
• rST selbst ist unabhängig von Sphinx, in der Praxis nutzt man rST aber häufig wegen Sphinx; deshalb werden beide hier gemeinsam behandelt

Strukturunterschiede zwischen Markdown und rST

• Der größte Unterschied ist, dass Markdown eher eine leichtgewichtige HTML-Auszeichnung ist, während rST eine mittelgroße Auszeichnungssprache ist, die einen abstrakten Dokumentbaum erzeugt
• Die Bildsyntax von Markdown kann schon durch eine einfache Transformation in HTML wie <img alt="alttext" src="example.jpg"/> umgewandelt werden
  • Auch moderne Markdown-Engines parsen oft in eine Zwischendarstellung, ihrem Grundcharakter nach bleibt Markdown aber eher eine leichte HTML-Schreibweise
• Bilder werden in rST mit der Direktive .. image:: dargestellt
  • Sphinx sucht den registrierten Directive-Handler und führt ImageDirective.run aus
  • Das Ergebnis ist ein Knotenobjekt wie image_node mit einem alt-Feld
  • Wenn die Verarbeitung des gesamten Doctree abgeschlossen ist, sucht der HTML Writer die Rendering-Funktion für image_node und gibt den HTML-Tag aus
• Der rST-Ansatz ist in Implementierung und Syntax komplexer und hat mehr Boilerplate als Markdown, behandelt Bilder aber über denselben Erweiterungsmechanismus wie andere Direktiven

Wie neue Dokumentobjekte hinzugefügt werden

• In rST/Sphinx lassen sich neue Textobjekte als Erweiterung hinzufügen
• Wenn man zum Beispiel statt <image> ein <figure> und ein <figcaption> erzeugen möchte, müsste man in einfachem Markdown HTML direkt einfügen
• In Sphinx erledigt man das, indem man eine neue figure-Direktive registriert
  • FigureDirective kann von ImageDirective erben und so den Großteil der Bildverarbeitung wiederverwenden
• Das Muster aus Registrierung einer Direktive, Erzeugung von Knoten und Registrierung builder-spezifischer Renderer gilt einheitlich für alle Erweiterungen

Doctree-Transformationen vor dem Rendering

• Sphinx kann vor dem Rendering Doctree-Transformationen ausführen
• Auch Querverweise zwischen Dokumenten werden über diese Funktion behandelt
  • Wenn ein Dokument einen foo-Anker enthält und ein anderes Dokument :ref:\image <foo>`` nutzt, fügt Sphinx in einem Nachverarbeitungsschritt die korrekte URL ein
• Transformationscode wird wie ein First-Class-Feature im Build-Prozess behandelt
  • Bestimmte Transformationen können nur bei HTML-Ausgabe angewendet werden
  • Transformationen können in bestimmten Build-Phasen ausgeführt werden
  • Auch eingebaute Transformationen, die man nicht ausführen möchte, lassen sich entfernen
• Nicht jedes Dokument braucht diese Leistungsfähigkeit; Markdown ist leichtgewichtig, portabel und deshalb weit verbreitet

Beispiel für eine Erweiterung mit Übungen und Lösungen

• Logic for Programmers ist ein stark mathematiknahes Buch und braucht daher Übungen für Leser
• Beim Schreiben ist es einfacher, Übungen und Lösungen im Dokument nah beieinander zu halten; für Leser sollen die Lösungen aber hinten im Buch erscheinen
• Die Anforderungen unterschieden sich je nach Ausgabeformat
  • Übungen und Lösungen müssen gegenseitig verlinkt sein
  • Wegen der Druckbarkeit braucht das PDF auch Seitenverweise
  • Die Darstellung muss sich zwischen LaTeX/PDF-Ausgabe und EPUB-Ausgabe unterscheiden
• Dafür wurde eine Custom Sphinx Extension geschrieben, die exercise, solution und solutionlist verarbeitet
• In der HTML-Debug-Ausgabe werden Übungen und Lösungen inline gerendert
• Bei der EPUB- und LaTeX-Erzeugung wird zunächst der gesamte Doctree erstellt und anschließend eine Transformation ausgeführt
  • Alle solution_node an ihrer ursprünglichen Position werden unter solutionlist verschoben
  • Jede Übung erhält einen Referenzknoten, der auf die neue Position der Lösung verweist
  • Jede Lösung erhält einen Referenzknoten zurück zur ursprünglichen Übung
• Der LaTeX-Builder umschließt Übungen und Lösungen mit einer answers environment
• Der EPUB-Builder rendert Lösungen als popup footnote
• Diese Struktur hilft auch beim Erstellen der kostenlosen Leseprobe des Buches
  • Am Ende der kostenlosen Leseprobe stehen nicht die Lösungen des gesamten Buchs, sondern nur die Lösungen der darin enthaltenen Teile

Syntaxvorlieben und Alternativen

• Der häufigste Einwand gegen rST ist, dass die Syntax hässlich ist
• Ein Werkzeug nicht zu verwenden, weil es einem optisch nicht gefällt, ist eine völlig legitime Entscheidung; auch warum Lisp manchen schwerfällt, lässt sich als dieselbe Geschmacksfrage betrachten
• Alternativen sind asciidoc, MyST, Typst, Pollen und pandoc-extended markdown
• Der Punkt ist nicht, dass Sphinx/rST außergewöhnlich gut für große Dokumentation ist, sondern dass einfaches Markdown außergewöhnlich ungeeignet für große Dokumentation ist

Grenzen Markdown-basierter Generatoren

• Einfaches Markdown hat keine einheitliche Erweiterungssyntax und keine native Unterstützung für Transformationen vor dem Rendering
• Viele Markdown-basierte Dokumentgeneratoren fügen eigene Preprocessing-Schritte hinzu, um neue Anwendungsfälle zu unterstützen
• Dieser Ansatz funktioniert meist, umgeht das Problem aber rund um Markdown, statt es innerhalb von Markdown zu behandeln
• Dadurch entsteht eine Grenze bei der Leistungsfähigkeit der Features, und Programmierwerkzeuge können diese Varianten schwerer verstehen
  • Für Markdown und rST gibt es LSP und treesitter, aber für gitbook-markdown, md-markdown oder leanpub-markdown sind Werkzeuge auf demselben Niveau kaum zu erwarten
• Die hässliche Syntax von rST kann sich im Gegenteil als Vorteil erweisen, weil der Syntaxbaum reichhaltiger ist
  • Eine treesitter-Abfrage, die nur den Body einer bestimmten todo-Direktive ändert, ist möglich
  • Das ist möglich, weil der rST-Syntaxbaum reichhaltiger ist als der Markdown-Syntaxbaum

Update zu Logic for Programmers

• Logic for Programmers ist ein Buch darüber, wie formale Logik in der alltäglichen Softwareentwicklung nützlich sein kann
• Das Buch beginnt mit einem Überblick über grundlegende Mathematik und führt dann zu 8 Anwendungen wie Property-Tests, Datenbank-Constraints und Entscheidungstabellen
• Es ist noch in der Alpha-Phase, umfasst aber 20.000 Wörter, und Leserfeedback ist willkommen

[GN⁺]

Meinungen auf Hacker News

• Wenn man mich fragt: „Würdest du ein gutes Werkzeug nicht benutzen, nur weil dir schon beim Anschauen übel wird?“, würde ich mit Ja antworten. Der größte Vorteil von Markdown ist, dass es leicht zu lesen ist; der zweitgrößte, dass es leicht zu schreiben ist.
  Wie einfach es zu parsen oder zu erweitern ist, spielt kaum eine Rolle. Unabhängig davon, ob Markdown die beste Wahl zum Schreiben von Büchern ist: Für den Zweck, schnell formatierten Text so zu schreiben, dass ihn auch Menschen ohne genaue Syntaxkenntnisse leicht lesen können, ist Markdown am besten. Ich will kein Buch schreiben, sondern nur Notizen, schnelle Dokumentation oder Kommentare verfassen; und wenn ich ein Buch schreiben würde, würde ich vor RST zuerst LaTeX verwenden.

  • Als Markdown unter Entwicklern populär wurde, wirkte das wie eine ziemlich seltsame Wahl. Schon damals gab es viele bessere Optionen, um Plain Text in formatierte Dokumente zu verwandeln, aber Entwickler bauten CMS, Produktivitäts-Apps, Dokumentenverwaltungstools und sogar Plugins rund um Markdown.
    Als ich es dann in echten Apps benutzte, zeigte sich: Darum ging es bei Markdown nicht. Ziel ist, nur minimale Formatierung bereitzustellen, sodass es schon als Plain Text so natürlich lesbar ist wie in HTML gerendert. Der unterstützte Formatierungsumfang ist absichtlich klein, sodass man ihn im Kopf behalten und ohne Toolbar verwenden kann. Für Kommentarfelder, Chats, Commit-Messages und vielleicht Blogposts passt das, aber nicht für das Erstellen von Enterprise-Produktdokumentation. Heute wird Markdown sogar dort verwendet, wo es gar nicht als HTML gerendert wird, weil es an sich gut lesbar ist; ich wünschte, HN würde es ebenfalls unterstützen.
  • Ich habe ein Buch in Markdown geschrieben und hatte keine nennenswerten Probleme. Es war zwar keine technische Dokumentation, sondern ein Roman, aber es gab nichts, was sich nicht mit Markdown und gelegentlich etwas HTML lösen ließ.
    Auch recht viel technische Dokumentation habe ich in Markdown erstellt, und mit den Pandoc-Erweiterungenhttps://pandoc.org/MANUAL.html kann man fast jede benötigte Formatierung einbauen, einschließlich komplexer Formeln und Codeblöcke mit Syntaxhervorhebung. Dieses Markdown lässt sich in HTML, Word-Dokumente, ePub, PDF usw. umwandeln. Um zu etwas anderem als Markdown zu greifen, bräuchte es schon einen sehr überzeugenden Grund.
  • Ich würde mich wohl ungefähr zu den oberen 10 % der TeX-Nutzer zählen, aber ich sehe nicht viel Raum für eine weitere Satzsprache zwischen Markdown und TeX. Markdown ist einfach, aber eingeschränkt, und TeX ist etwas schwierig, aber praktisch unbegrenzt flexibel.
    Das größte Problem, das ich bei TeX sehe, ist nicht die Sprache, sondern die Menschen. Leute schreiben oft Spaghetti-TeX in miserablen Stilen. Wenn man aber mit der Denkweise „Dokumente sind Code“ herangeht, kommen ziemlich saubere Ergebnisse heraus. Das zweitgrößte Problem ist, dass es keinen guten TeX-→-HTML-Compiler gibt.
  • „Wenn ich ein Buch schreiben würde, würde ich LaTeX verwenden“ klingt für die Phase des Schreibens und Strukturierens nach einer furchtbaren Wahl. Ich würde lieber in Markdown schreiben, mich nicht um den Satz kümmern und erst in der Veröffentlichungsphase nach LaTeX konvertieren.
    Ich bin in LaTeX nicht besonders geübt, aber als ich einmal versuchte, es zu lernen, fühlte es sich an, als würde ich die Sprache einer insektoiden Alien-Zivilisation lernen. Es ist überhaupt nicht intuitiv, und etwas Neues zu machen war fast unmöglich, wenn man nicht einfach kopierte, was jemand anderes schon erledigt hatte, und nur den eigenen Text einsetzte. Soweit ich mich erinnere, gab es auch keine erstklassige Unicode-Unterstützung.
  • Der Aussage, Markdown sei „das beste Werkzeug, um schnell formatierten Text so zu schreiben, dass ihn auch Menschen ohne genaue Syntaxkenntnisse leicht lesen können“, kann ich schwer zustimmen. Schon bei den Grundlagen ist es nicht das Beste.
    Für Kursivschrift Sternchen oder Unterstriche zu verwenden, erfordert ebenfalls Gewöhnung; es gibt deutlich intuitivere Varianten wie /italic slashes/. Sobald man über die Grundlagen hinausgeht, verdecken Tabellen, Metadaten und Tags den Text, sodass Schreiben und Lesen ohne passende Werkzeuge nicht mehr einfach sind. Wenn Erweiterung einfach ist, lassen sich auch solche Grundprobleme beheben, daher ist Erweiterbarkeit durchaus relevant.

• Ich habe etwa 12 Jahre als technische Redakteurin bzw. technischer Redakteur gearbeitet und früh in meiner Karriere die Dokumentation eines Startups von Word nach Sphinx migriert. Danach habe ich an Googles eigenem CMS bzw. Entwicklerdokumentationsplattform gearbeitet, an einer Eleventy-basierten Site und in den letzten zwei Jahren wieder an einer Sphinx-basierten Site, pigweed.dev. Außerdem habe ich für ein Startup mit readme.com gearbeitet und mich auch etwas mit Docusaurus, Astro und Hugo beschäftigt.
  reStructuredText allein kann sperrig sein, aber reST in Kombination mit Sphinx ist ausgesprochen gut. Die Stärken von Sphinx überwiegen die Schwächen von reST bei Weitem. Für große professionelle Dokumentationssites mit mehr als 100 Seiten und mehr als 10 Beitragenden halte ich Sphinx langfristig ziemlich klar für die verantwortungsvollste Wahl. Bei Pigweed haben wir zum Beispiel eingerichtet, dass schon :bug:\59385981`` in einen Link auf https://pwbug.dev/59385981 umgewandelt wird; und falls später Bug-Links massenhaft migriert werden müssen, ist das einfach. Auch bei internen Links ist immer gewährleistet, dass sie aufgelöst werden, und wenn man auf etwas Nichtvorhandenes verlinkt, gibt es eine Warnung oder einen Fehler. Dass das nicht Standard für Dokumentationssites ist, fand ich schon früher seltsam und habe darüber auf https://technicalwriting.dev/src/link-text-automation.html geschrieben. Sphinx hat außerdem gut definierte Erweiterungs- und Theme-APIs, und auf PyPI gibt es ein ziemlich großes Ökosystem. Heutzutage nenne ich Sphinx den schlafenden Riesen unter den Dokumentationssystemen; mit nur etwas gebündelter Kraft könnte es noch deutlich großartiger werden.

  • Dieser Punkt ist wirklich wichtig. Es gibt viel zu viele CMS und statische Site-Generatoren, bei denen man beim Schreiben die endgültige URL direkt eintragen muss.
    Wenn sich der Slug ändert oder die Site-Struktur umgebaut wird, muss man auf der gesamten Site Suchen und Ersetzen durchführen. Statische Site-Generatoren könnten einen eigentlich Links wie [Hello](../hello.md) setzen und sie beim Build auflösen lassen, aber viele der Tools, die ich genutzt oder mir angesehen habe, verlangen, dass man [Hello](/why/hello/) direkt eintippt. Diese Funktion scheint die Geister zu scheiden. Als ich mit einem Teammitglied eines statischen Site-Generators darüber sprach, bekam ich nur die Antwort: „Warum willst du das überhaupt?“, und selbst nach einer Erklärung kam es nicht an. Ich weiß nicht, ob man erst selbst das Problem erlebt haben muss, um den Wert der Lösung zu erkennen, oder ob manche einfach daran gewöhnt sind, etwas einmal zu schreiben und nicht über mehr als 10 Jahre zu warten. Ich fände es jedenfalls gut, wenn das breiter unterstützt würde.
  • Sphinx ist großartig, aber massiv unterschätzt. Soweit ich weiß, ist Sphinx das einzige Dokumentationsframework, das strukturell solide, erweiterbar und weit verbreitet ist.
    Das Plugin-Ökosystem ist hervorragend und bietet enorme Hebelwirkung, um die Dokumentation von Teams und Projekten zu verbessern. reStructuredText selbst mag ich nicht, aber dank MyST-Parser kann man heute vieles, wofür Sphinx früher stark an RST gebunden war, auch mit Markdown erledigen: https://github.com/executablebooks/MyST-Parser
  • Gemeinsame Site-Elemente zu customizen war auch mit Markdown+Pandoc sehr einfach. Ein Image-Tag mit YouTube-Link in ein Video-Tag plus Thumbnail mit Alternativtext umzuwandeln und Image-Tags für lokale Videodateien an ffmpeg anzubinden, um sie zu optimieren und zu skalieren, ließ sich mit ein paar Zeilen Code erledigen.
  • Bis ich diesen Kommentar gesehen habe, kannte ich Sphinx nicht. Ich schreibe seit über 20 Jahren neben meiner Entwicklungsarbeit technische Dokumentation und war bisher eher in der Nähe von TeX und eigenem XSL unterwegs.
    Ich habe gerade ein Buch mit über 200 Seiten über eine interne Sprache/VM/Abstraktionsschicht nach Sphinx migriert, und es ist wirklich ein lebensveränderndes System. Ich wünschte, die Sphinx-Dokumentation selbst hätte eine niedrigere Einstiegshürde oder mehr Beispiele, aber im Moment fühlt es sich nach einer ziemlich intensiven Honeymoon-Phase an. Mein Hauptinteresse gilt der Frage, wie man daraus schön aussehende PDF-Bücher erzeugt und wie man das Buch kapitel- und abschnittsweise in POSIX-kompatible man-Pages zerlegt.
  • Wenn Sphinx beim Mainstream richtig erfolgreich werden soll, ist Priorität Nr. 1, hochwertige, schöne Themes zu bekommen.
    Beim Auswählen eines Site-Generators ist Ästhetik ein ziemlich wichtiger Faktor. Hugo und Gatsby haben hervorragende Standard-Themes, und ich habe sie tatsächlich schon allein aus diesem Grund für Projekte gewählt. Die Sphinx-Theme-Sammlungen https://sphinx-themes.org/ und https://sphinxthemes.com/#featured-themes wirken größtenteils eher blass. Vergleicht man das Standard-Theme Sphinx RTD https://sphinx-rtd-theme.readthedocs.io/en/stable/ mit Apples Dokumentation https://developer.apple.com/documentation/swift/array oder Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default, sieht es veraltet aus.

• Ich halte den Satz „Markdown ist eine leichtgewichtige Darstellung von HTML“ für das größte Problem in diesem Text. Das ist eindeutig ungenau.
  Markdown wurde als Werkzeug entworfen, um Textformatierungs-Konventionen zu konvertieren, die in E-Mails und Usenet-Beiträgen Anfang der 1990er praktisch als Standard verwendet wurden. Wegen der Beschränkung auf 7-Bit-ASCII wurden Formatierungen wie Hervorhebungen oder Überschriften mit Sonderzeichen markiert, und HTML hatte mit diesen namenlosen Konventionen viele Gemeinsamkeiten. Deshalb schrieb John Gruber 2004 ein grundlegendes Skript https://daringfireball.net/projects/markdown/, das sie in HTML umwandelte, aber er hätte wohl nicht erwartet, dass es zu einem so verbreiteten De-facto-Standard werden würde.

  • Der erste Satz dieses Links lautet direkt: „Markdown is a text-to-HTML conversion tool for web writers.“
    Gruber hat nicht einfach den De-facto-Standard aus dem Usenet genommen und einen HTML-Konverter gebaut, sondern aus Usenet und anderen Konventionen Anleihen genommen und sein eigenes Markup entworfen. Auch die „Acknowledgements“ am Ende des Links zeigen das. Markdown war von Anfang an als Markup-Syntax für Web-CMS gedacht, und es ist richtig, es als leichtgewichtige Darstellung von HTML zu bezeichnen. Der Kern war, dass jeder Teil der Syntax direkt entsprechendes HTML erzeugt.
  • Dem stimme ich nicht zu. Markdown hatte immer einen Bezug zu HTML, so sehr, dass Markdown-Parser sogar das Mischen mit echten HTML-Tags unterstützen.
    Die Tatsache, dass es von E-Mail-Konventionen inspiriert wurde, macht die Aussage „Markdown ist eine leichtgewichtige Darstellung von HTML“ nicht weniger zutreffend.
  • Ich wünschte, diese Art semantischer Streit würde aufhören. Sie erzeugt langweilige Diskussionen und verstößt auch gegen die HN-Guidelines.
    Es gibt die Regel, auf die plausibelste und stärkste Interpretation dessen zu antworten, was das Gegenüber gesagt hat, statt sich die schwache Interpretation herauszugreifen, die leicht zu kritisieren ist. Es gibt auch die Regel, sich nicht den provokantesten Satz eines Artikels herauszupicken und darüber zu klagen, sondern auf die interessanten Teile zu antworten: https://news.ycombinator.com/newsguidelines.html
    Wenn man dem Kern des Artikels nicht zustimmt, kann man sagen, dass man Markdown gegenüber rST bevorzugt, und erklären, warum. Sich über einen einzelnen Satz darüber zu streiten, was Markdown genau ist, ist albern.
  • Markdown selbst ist von E-Mail- und Usenet-Formatierung zu unterscheiden. Markdown war eine bestimmte Syntax, schlecht definiert, und hat sich später zu mehreren weitgehend ähnlichen Syntax-Familien ausgeweitet.
    Es war zwar von Konventionen wie E-Mail oder Usenet inspiriert, und einige davon gab es sogar schon vor Computern. Ich meine zum Beispiel, alte maschinengeschriebene Dokumente gesehen zu haben, in denen Sternchen wie Kursivschrift verwendet wurden. Aber Markdown ist stark mit HTML verbunden, seine Syntax ist sehr stark durch HTML eingeschränkt, und Versuche, es von HTML zu trennen, sind größtenteils zum Scheitern verurteilt.
  • Beides stimmt. Die ursprüngliche Implementierung war eine Obermenge von HTML. Übliches schreibt man in der leichten Syntax, den Rest in HTML.

• Ich denke, der Kern von Markdown besteht darin, einfache Dinge schneller zu machen als mit rohem HTML, aber bei Bedarf rohes HTML einmischen zu können.
  Bei Projekten, in denen ich die Mächtigkeit von RST gegenüber Markdown gebraucht hätte, war es für mich bequemer, gleich HTML direkt zu schreiben.

  • Wenn jemand wie der Autor schreibt: „Man kann Sphinx erweitern und neue Textobjekte erstellen. In einfachem Markdown muss man HTML direkt einfügen“, frage ich mich, was daran falsch ist, einfach HTML zu verwenden, wenn man diese Funktion braucht. Ich verstehe nicht, warum man noch eine zusätzliche Schicht einziehen sollte.

• Beim Aufbau eines Dokumentationssystems mit ähnlicher Komplexität habe ich RST geprüft, weil ich Markup mit klarer Semantik dringend brauchte: Die Struktur von RST-Dateien sollte in einer Datenbank gespeichert und Datenbankergebnisse mit Inhalten vermischt werden.
  Ich stieß auf zwei Probleme. Erstens haben die RST-Tools keinen Unparser, der wieder RST ausgibt. Ich wollte mehrere RST-Dateien und andere Quellen zusammenführen, automatisch RST-Dateien erzeugen und sie über eine Dokument-API bearbeiten, aber das wurde nicht unterstützt. Zweitens erwarten RST-Tools eine für ein bestimmtes Dokument definierte Menge von Blöcken. Wenn Blöcke allgemein ausgedrückt würden, wären Tools möglich, die Dokumente transformieren, ohne die internen Blockdefinitionen zu kennen; so ist es aber nicht. Das ist eher ein Tooling-Problem als ein Problem von RST selbst, aber jedes Mal, wenn man den Code bis auf den Grund freilegen muss, denkt man an andere Markup-Systeme, etwa HTML-basierte.

  • Statt HTML kann man strukturierte Dokumente mit XML schreiben. In XML kann man die benötigten Custom Tags definieren und, wenn man möchte, auch Schema-Validierung nutzen.
    Der Vorteil dieses Ansatzes ist, dass man Eingabeschema und Ausgabe vollständig kontrollieren kann; der Nachteil ist, dass die Syntax deutlich mehr Rauschen hat als Markdown oder RST und dass man Skripte braucht, um in das gewünschte Ausgabeformat zu parsen und zu transformieren.
  • In Python ist rST nur eines von mehreren Eingabeformaten, die docutils unterstützt: https://docutils.sourceforge.io/README.html#purpose
    Der gesamte Zweck von docutils ist es, Formate zu parsen und in eine API zu überführen: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
  • rST und AsciiDoc wirken funktional ungefähr ähnlich. Ich frage mich, ob auch ihre Schwächen und fehlenden Funktionen ungefähr ähnlich sind.
  • Ich war Committer bei docutils, dem wichtigsten Tool für rST. Einer der Gründe, warum ich die Tools auf Markdown umgestellt habe, war, dass der Umgang mit docutils einfach zu schmerzhaft war. Schon die Weigerung, zu Orten wie GitHub umzuziehen, zeigt, wie unfreundlich die Zusammenarbeit damit ist.
  • Ich habe gerade keinen Computer und kann es nicht testen, aber ich vermute, dass man mit der include-Direktive das Gewünschte erreichen kann.

• Vor ein paar Jahren habe ich einmal eine Teilmenge von reStructuredText zusammengestellt, die es sich zu merken lohnt: https://simonwillison.net/2018/Aug/25/restructuredtext/
  In jüngeren Projekten habe ich angefangen, MyST zu verwenden: Es bietet die Referenz- und Inhaltsverzeichnis-Funktionen, die ich an reStructuredText wichtig fand, erlaubt Beitragenden aber zugleich die leichter zu schreibende Markdown-Syntax.

  • Besonders groß sind die Vorteile bei Links, insbesondere bei externen Links. Auf einer Dokumentationssite kann derselbe externe Link an mehreren Stellen referenziert werden, und wenn er sich ändert, möchte man ihn nur einmal aktualisieren müssen.
    Der eigentliche Gamechanger sind bei internen Links rST+Sphinx und die Direktiven :ref: und :doc:. Wenn man innerhalb desselben Inhalts auf Anker oder Dokument-Links verweist, muss man die Überschrift nicht direkt eintippen und vermeidet, dass eine manuell eingetragene Überschrift irgendwann veraltet: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
    Das ist eine der Funktionen, die ich beim Schreiben in rST am meisten vermisse.

• Ich will die ReStructuredText-Diskussion nicht kapern, aber wenn ihr nach einer Markup-Sprache sucht, die mehr bietet als Markdown, würde ich empfehlen, euch statt ReStructuredText AsciiDoc anzusehen. Ich habe über Jahre technische Dokumentation in allen drei Formaten geschrieben und halte AsciiDoc für besser als ReStructuredText und Markdown.
  Zum Beispiel ist die Tabellenunterstützung in Markdown und ReStructuredText ziemlich umständlich. Das Tabellenformat von AsciiDoc ist leicht zu lesen, zu schreiben und zu pflegen, unterstützt Header, Captions, benutzerdefinierte Größen für Tabellen und Zeilen sowie komplexe Formatierung innerhalb von Tabellen und ist damit leistungsfähiger. Es ist ein einziges Standardformat ohne die vielen Dialekte wie bei Markdown, die Syntax ist knapp und gut lesbar, und die Lernkurve ist flacher als bei ReStructuredText. Die Optionen fürs Output-Styling sind besser, die Toolchain ist überlegen, und es gibt viele eingebaute Dokumentationsfunktionen, sodass man seltener von Third-Party-Plugins abhängt. AsciiDoc wurde von Anfang an für technische Dokumentation entworfen; die beiden anderen wurden eher in diese Rolle hineingezwängt.

• Wenn man ein Markdown-Dokument von etwa 5 bis 10 Seiten hübsch strukturiert und es selbst aus dynamischeren Jinja-Templates rendern lässt, fühlt sich der Start ziemlich zufriedenstellend an. Es gibt auch einen Build-Prozess für automatische Doku, und für eine einzelne GitHub-README ist es schon zu groß. Aber genau dann beginnt der Schmerz.
  GitHub-Projektseiten-Dokumentation passt nicht so richtig, man ist unsicher, ob eine .nojekyl-Datei nötig ist oder ob man noch einen gh-pages-Branch braucht. Man weiß nicht, ob es ein Fehler in den Repository-Einstellungen ist oder ob Änderungen einfach nicht übernommen wurden, und nach ein paar Stunden mit GitHub Actions wird es irrational. Wenn man sich Read the Docs wieder ansieht, scheint es Sphinx zu wollen, also verbindet man Markdown mit Sphinx; der Build läuft, aber nach dem Deployment ist die Seitenbreite kaputt, lokal lässt sich das nicht reproduzieren, also liegt es vermutlich an den eingeblendeten Anzeigen im Community-Tier. Bei vielen Projekten funktioniert das gut, und ich habe es auch selbst schon gemacht, aber bis es läuft, ist es unglaublich kleinteilig und heikel. Am Ende ist Markdown gegen RST gar nicht das Thema; entscheidend ist, eine Kombination zu finden, die gut zu mittelgroßen Dokumentationsprojekten und statischem Hosting passt.

  • Ich frage mich, ob du dir mdBook angesehen hast. Ich habe es selbst nicht benutzt, fand aber die Dokumentation mehrerer Projekte, die mdBook verwenden, gut, und ab dem Punkt, an dem eine einzelne README-Datei nicht mehr reicht, wirkt es ziemlich brauchbar.
    Auch die Anleitung für automatisches Deployment ist gut gemacht: https://github.com/rust-lang/mdBook

• Es scheint übersehen zu werden, dass der Autor im Kontext des Satzes seines eigenen Buchs spricht. Er behauptet nicht allgemein, rST sei besser als Markdown.
  Im Allgemeinen ist die Einfachheit von Markdown der Grund für seine weite Verbreitung, aber das ist nicht der Anwendungsfall, über den der Autor spricht.

• Es ist interessant, wie manche so reagieren, als wäre reST als Konkurrent zu Markdown entstanden. Tatsächlich ist es eher umgekehrt. reST ist eine Weiterentwicklung von StructuredText aus dem Jahr 2002, während Markdown 2004 erstmals veröffentlicht wurde.
  Die Ziele beider Formate sind sehr ähnlich, und bei ganz grundlegendem Text lassen sich beide wie normaler Klartext lesen und schreiben. In dieser Zeit wollten plötzlich alle so etwas, und es entstanden mehrere Formate. Dass Markdown gewonnen hat, hat meiner Ansicht nach wenig damit zu tun, dass es „einfacher“ oder „lesbarer“ wäre. Bei Inhalten, die sich leicht mit reinem ASCII und Leerzeichen ausdrücken lassen, sind sie größtenteils austauschbar. Würde jemand sagen, das reST-Dokument im Beispiel sei ohne Parser unlesbarer Kauderwelsch? Ich sehe nicht recht, inwiefern eine Markdown-Variante dabei besser wäre; es ist eher ein historischer Zufall, dass sich eines stärker durchgesetzt hat, und beide sind für ihre Kernziele völlig ausreichend.

  • Es wurde ein sehr einfaches Beispiel gewählt, deshalb können sowohl Markdown als auch reST problemlos damit umgehen.
    reST bietet bei Bedarf viele nützliche zusätzliche Formatierungsfunktionen, aber wenn man sie nicht braucht, sind sie Ballast. Ich habe ungefähr 2010, als ich mich bei GitHub registrierte, angefangen, GitHub-flavored Markdown zu verwenden, und wegen der Python-Dokumentation auch ein paar Mal reStructuredText benutzt. Letzteres hatte eine deutlich steilere Lernkurve, und danach hatte ich keinen Grund mehr, es zu verwenden.
  • Unlesbar? Nein. Frustrierend zu tippen? Ja. Unterstrichene Überschriften sind beim Bearbeiten lästig, und selbst wenn die Länge nicht exakt passen muss, entsteht der Druck, sie doch passend zu machen.
    Auch doppelte Backticks sind eine Syntax, die im Verhältnis zur tatsächlich benötigten Zeit übermäßig nervt.