Dateiformat und Übersetzprogramm für Dokumentation und Sprache in Programmen oder Bibliotheken

Je exotischer, desto mehr Probleme später. Wichtig wäre, dass man Jahre später ohne spezielle Tools alles einfach lesen und durchsuchen kann.

Lu schrieb:

Wichtig wäre, dass man Jahre später ohne spezielle Tools alles einfach lesen und durchsuchen kann.

Ja, da stimme ich zu. Deshalb habe ich ja zumindest bei PDF Dokumentationen von einen Office Bearbeitungsprogramm (LibreOffice, MS Office, ...) auf LaTeX gewechselt. Da ist zumindest der Inhalt bis auf die "paar" Steuerbefehle und Formatierungsbefehle noch mit einen ganz normalen Texteditor lesbar. Aber da hilft auch Syntaxhighlighting um die Befehle zu erkennen. Zugegeben mit dem "normalen" Windows Texteditor würde ich mir ein LaTeX Dokument nur zur Not ansehen. Verstehe bis heute nicht warum der Standard-Texteditor von Windows kein Highlighting kann. Aber zumindest erkennt er seit einiger Zeit auch Unix Zeilenenden (LF). War soweit ich weiß zu Windows 95 Zeiten nicht der Fall.

Johannes schrieb:

Mich würde interessieren was Ihr für Dokumentation und Sprachausgabe für eure Programme verwendet. Also zum Beispiel bei CLI Programmen die Manpage und für die Bedienung passend in der jeweiligen Benutzersprache (Deutsch, Englisch, ...).

Heute? Markdown. Das ist ein einfaches Textformat, das sich einfach durchsuchen und mit pandoc [1] in quasi alles Mögliche umwandeln läßt. Zudem ist es erweiterbar, zum Beispiel können die Markdown-Dateien mit der Frontmatter-Erweiterung mit strukturierten YAML-Daten angereichert werden. Und der Clou: Markdown ist sehr leicht menschenlesbar, jedenfalls im Vergleich mit HTML, LaTeX, DocBook und Co.

[1] https://pandoc.org/

Ich habe mir ja für PDF Dokumentationen LaTeX angeeignet.

Das kann ich zwar auch, aber bei meinen Programmen ist mir wichtig, daß die Dokumentation für die Benutzer möglichst leicht zugänglich ist. Da hat Markdown den großen Vorteil, daß es weder eine GUI noch zusätzliche Software braucht, sondern einfach mit less(1), more(1) oder sogar cat(1) gelesen werden kann -- auch über langsame Netzwerke und auch von Laien, die dem Markdown-Format noch nie vorher begegnet sind. (Wobei solche Nutzer zumindest im technikorientierten Umfeld mittlerweile ziemlich selten geworden sind.)