Org-Mode und DocSet#

Heute die Meldung, das Mozilla die Dokumentation von HTML auf Markdown umgestellt hat. Ich finde Markdown zu einfach und es bietet nicht die Möglichkeiten die Sphinx mit dem Rest-Format (Restructured Text) bietet. Alternativen werden immer wieder diskutiert z.B. die Verwendung von org-Dateien die ihren Ursprung im Emacs-Universum haben. Mit dem ersten Kontakt, hatte ich die Philosophie nicht sofort verstanden! Ein zweiter Anlauf mit Bezug zum org-roam-Mode hat mir dann die Augen geöffnet. Daraus ist nun eine Leidenschaft geworden, so auch für diesen Blog. Daraus ist, für viele Arten der Dokumentation, der folgende Workflow entstanden:

image0

Inhalt als Rohling (im Org-Format)#

Man beginnt mit einer org-Datei und beschränkt sich auf erste einfache Strukuren:

  • Überschriften

  • Listen

  • Bilder

Später kommen dann noch Tabellen, Quellcode-Schnipsel und andere Dinge dazu. Was möglich ist und von mir ausprobiert wurde, kann auf zwei Tutorialseiten nachgelesen werden [1] , [2]. Sie dienen mir auch als »Second Brain«, falls ich einen speziellen Anwendungsfall noch mal nachschlagen muss. Das Gehirn ist halt ein Sieb!

Export#

Zwei Wege sind möglich:

  • konvertieren mit dem Programm »pandoc«

    pandoc -f org -t rst neue-inhlate.org > rest-fuer-sphinx.rst

  • export mit einer Erweiterung für den Emacs (rst-mode)

    image1

Nun ist der Rohling für Sphinx vorbereitet und kann in die Dokumentation, in diesem Fall in den Blog eingebunden werden.

»Warum etwas einfach halten, wenn es auch kompliziert geht.«, möchte man meinen, aber ich bin damit zufrieden, weil der org-mode nach einer gewissen Einarbeitungsphase gut zu handhaben ist und ein entspanntes Schreiben befördert. Dabei helfen natürlich diverse Tastenkombinationen, was im Emacs Standard ist und nicht zu vergessen, die Erweiterungen von »YASnippet«, einem Textbausteinsystem sind einfach genial (wie viele Dinge im Emacs).

Von Sphinx zum DocSet#

In einen aktuellen Artikel hat mich Hynek Slavie auf das Docset-Konzept von Dash aufmerksam gemacht. Primär für den Offline-Dokumenten-Reader »Dash« (MacOS) entwickelt, können die DocSets unter Windows und Linux mit dem alternativen Reader »Zeal« gelesen werden.

Was ist an dem Reader/DocSet besonders?

  1. Offline-Reader

  2. irre guter Index, der eine superschnelle Suche anbietet

  3. Bei Weitergabe benötigt der Konsument nur die Programme (Dash/Zeal) und das passende Docset. Viele DocSets lassen sich aus dem Netz direkt herunterladen.

Ein erstes Experiment mit Lehrlingen, die in zwei Tagen mit Windows in der Lage waren und neu gelernt haben:

  • mit dem EMACS rst-Dateien zu erstellen

  • ein Virtual Environment für Python einzurichten

  • ein Setup für Sphinx zu erstellen

  • mit docs2dash den Sphinx-Rohling ins DocSet-Format zu konvertieren

Die Freude über die selbstgeschaffene Dokumentation hat die Mühen vergessen lassen.

Bin gespannt, ob die Burschen dran bleiben…

Nachtrag vom 09.07.2023:

Zeal, Suchmaschinen und Bücher sind bei der Jugend »out«! Sie verwenden ChatGPT, es gibt aber ein Problem: Man muss die Vorschläge auch mit dem eigenen Wissen abgleichen können und da entsteht eine Lücke, eine Wissenslücke. Auch kurzzeitiger Ausfall des Systems läßt die ChatGPT-Jünger ziemlich blaß aussehen…

Fußnoten#