ReStructuredText

Dokumenttechnik: restructuredText

Seit 2017 erstelle ich neue Seminarunterlagen in restructuredText (RST) und wandele bestehende Dokumentationen und Seminarbegleitungen in RST um.

Für gelegentliche „Typos“, die schon verhanden waren oder beim Konvertieren entstanden sind, bitte ich um Verständnis. Bitte einfach unter Angabe der Kapitel-Info an mich übermitteln. Hierfür Danke im Voraus.

Für Kenner meiner Seminarunterlagen hier kurz die wichtigsten Gründe für die teils aufwändigen Arbeiten:

Flexibilität

Word- (.docx), LibreOffice- (.odt) und PDF-Dokumente lassen sich zwar einfach erstellen!

Aber solche Dokumente lassen sich leider überhaupt nicht geeignet und sauber in HTML (gegliedert / oder als eine Seite), JSON, XML, Manpages, Texinfo oder gar EPUB wandeln!

Metainfos

Meta-Techniken, Fußnoten oder Indizes lassen sich einheitlich in den unterschiedlichen Formaten pflegen.

Versionsmanagement

Eine Versionsverwaltung wie Git (Plattform: github.com) arbeitet am effizientesten mit einfachen Textdokumenten - kann aber natürlich auch binäre Objekte handeln. Auch manuelles „Diffen“ ist mit Rohtexten eine mächtige und einfache Technik, während bei Word/PDF-Dokumenten immer sehr aufwändige und unübersichtliche Techniken eingesetzt werden müssen.

Conclusio: man nutze ein einziges grundlegendes Dokumentformat restructuredText und Werkzeuge (RstTools, DocUtils, Pandoc oder Sphinx) zum sauberen Erzeugen der gewünschten Dokumentformate (HTML, SingleHTML, Latex, PDF, EPUB, ODT, DOCX,…)

Ihr Trainer Joe Brandes - Braunschweig, 2020